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

  1. 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

  2. When the service account is created and claimed go to website developer.dartmouth.edu and click on the Manage Keys button.

  1. 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.

  2. Click the Create New Key button, enter a purpose 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.

  3. 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!

  4. 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 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:

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