Dartmouth API Developer Portal
Introduction
The Dartmouth Enterprise API (DartAPI) is available to all Dartmouth affiliated entities. The API provides programmatic access to a large amount of functionality, allowing customers to extend the DartAPI platform. This page is targeted at developers; for more general API information, see the Getting Started page.
Schema
All API access is over HTTPS, using the standard set of HTTP verbs (POST, GET, PUT, DELETE) for CRUD operations (respectively). Data is returned in JSON format unless noted otherwise. All API endpoints begin with:
https://api.dartmouth.edu/api/
Please note that DartAPI requires successful authentication to the DartAPI Login Service as documented below. Application Developers must apply for a Dartmouth Service Account through Dartmouth's Help Desk.
Requesting a Dartmouth Service Account
Our process to acquire an API Key is currently a manual process. In future versions we anticipate a self service model that will allow developers to apply for api keys through this site.
Steps
Request a service account through the Dartmouth Help Desk this can be done through the following request form https://services.dartmouth.edu/TDClient/1806/Portal/Requests/ServiceDet?ID=30581
When the service account is created and claimed go to website
developer.dartmouth.edu
and click on theManage Keys
button.
Authenticate as the service account (this may require creating a private browser window). NOTE: that IE is not a supported browser, use Firefox or Chrome.
Click the
Create New Key
button, enter apurpose
note to remind you why you have created this key. One account can have multiple keys, a best practice is to create keys for particular use cases or applications. When the key for a particular use case completes (eg. and application is retired) the key can be deleted without impacting other use cases. Also at this time enter an expiration date of the key if there is a predetermined end date for the keys use.Copy the key and store is securely in a password vault. This key opens the door to the APIs and should be managed as securely as any password!
Test the login service by calling the login service as documented in the Authentication section of this document.
System Availability and Outages
DartAPI endevours to be available as a 24x7 service wherever possible. However some resources are directly tied to backend systems that occasionally experience planned or unplanned outages. During these periods API calls may result in 50x level return codes from the service. Subscription to the DartPulse notification system will help you identify when these events occur.
Subscribing to DartPulse
Navigate to:
http://dartpulse.dartmouth.edu/
Look at the right hand pane to find information about consuming the DartPulse notifications starting with Getting Started
. Also use the Outage calendar
to find planned periods of maintenance.
Regularly Scheduled Patching
Every month regular monthly patching occurs to keep systems up to date and secure. This normally follows a regular schedule of the 3rd Thursday of each month from 2am to 7am Eastern Time Zone. Occasionally there are emergency patches that must be applied off-schedule to prevent security breachs and these are posted on DartPulse as soon as possible.
Authentication
Calling the DartAPI Login Service
All API calls to DartAPI must contain an authentication/authorization token called a JWT (JSON Web Token) in the Authentication: Bearer header of the call.
The DartAPI Login Service provides this functionality by turning your API key into JWT. A JWT contains a json payload that describes
- the identity of the caller
- the email address of the caller
- the issuer of the jwt
- an issuer date/time
- an expiration date/time
The jwt is encrypted and digitially signed by the DartAPI authentication provider providing a secure mechanism for APIs to enforce authentication at the front door of the api, and enforce authorization decisions within the API call itself.
See the Authentication and Authorization section under Resource APIs for details on calling the Login Service
General Ground Rules
HTTP Verbs
Where possible, DartAPI strives to use appropriate HTTP verbs for each action:
GET: Used for retrieving resources. All requests made using this method are idempotent.
POST: Used for creating resources.
PUT: Used for updating resources.
DELETE: Used for deleting resources.
Client Errors
Whenever a request is not successful, the API will return a non-200 OK status and try to provide a useful error message in the following format:
curl -i 'https://api.DartAPI.com/api/v2/accounts/424242?key=dd6b9d2beb614611c5eb9f56c34b743d1d86f385'
HTTP/1.1 404 Not Found Connection: close Date: Thu, 21 Jun 2012 17:08:16 GMT X-UA-Compatible: IE=Edge X-Runtime: 2.398011 Content-Type: application/json; charset=utf-8 Content-Length: 52 Cache-Control: no-cache
{"message":"Couldn't find Account with id = 424242"}
Failing to pass a valid key parameter for authentication will result in a 401 Unauthorized response.
Trying to access a resource which does not exist (by id or other attribute, like username) will result in a 404 Not Found response.
Sending invalid attributes for a resource will result in a 422 Unprocessable Entity response, and, usually, a detailed error message explaining the issues with the attributes passed.
Coding for Future Use
DartAPI strives to keep forward and backward compatibility in mind when designing APIs. Simply put, our approach is to deliver essential api functionality with the idea that additions to increase functionality will not break existing consumers. Subtractions or removal of functionality will be avoided in all possibile situations. As a consumer you can take steps in your application to guard against future api enrichment by following these simple design patterns:
- always follow links to subresources or methods as they are presented by the api as they may change in the future. That is do not take shortcuts by hardcoding what seems an obvious return value link.
- we expect payload attributes to increase over time, so do not code for current attributes only.
Testing Environments
For early testing and acceptance you may be directed to try client programs against the pre-production release of an API. This will be fronted with a URL of the form:
https://api-preprod.dartmouth.edu/api