API Documentation

The DMPTool provides ongoing support two main threads of it's API due to varying needs of specific audience types. The threads are referred to as 'Version 0' which supports the early needs of organizational administrators and 'Version 1+' provides support for ongoing networked DMP (maDMP) use cases.

Table of Contents

1. Current Release Documentation
2. Version 0
3. Version 1+
4. Versioning Policy
5. Standard JSON Responses (V1+)
6. API Errors (V1+)
7. Pagination (V1+)
8. Doorkeeper Configuration (V2+)
9. Authorization Code Scoping (V2+)
10. Further Reading on OAuth (V2+)

Version 0

Version zero was designed to provide organizational administrators with access to the full text of all of their user's plans. We continue to support this version of the API because it's functionality does not tie into the use cases supported by the other versions of the API at this time. Please note that this version has support long term and will be patched only to provide necessary security updates.

• See the Documentation for V0

Latest Version

The V1+ versions of the API are designed for integrations with other systems and applications. They use the RDA common metadata standard for DMPs to communicate metadata about a DMP. They do not provide access to the full text narrative portion of a DMP (aside from the ability to download a PDF).

• See the Documentation for V1 - current major release
• See the Documentation for V2 - release candidate (beta)

Versioning Policy

While we provide ongoing support for V0, the V1+ API only receives support for the 2 most recent versions. When a new major API version is released, we guarantee full support for the latest version. In addition, we give 12 months notice before retiring the previous major version, and send periodic reminder emails to those members still using it during the notice period.

New major versions are required whenever the changes would break the current major version. For example the removal of an endpoint, changing the parameters expected by an endpoint or altering the format of any JSON input/output that would negatively impact existing integrations.

The DMPTool may make non-breaking changes to the current API version’s that do not break the structures of the expected inputs and outputs of the API. For example, adding additional (optional) fields to a JSON input or output, changing which DMPs are returned, etc.

• Users of the most recent API version are free to ignore these changes, but should be aware that they can be made
• Users of the previous API version will not receive these changes

New functionality will only ever be added to the latest version of the API so it is best to upgrade your integrations to the latest version when possible.

When developing a new major API version the DMPTool will attempt to produce ‘release candidate’ versions. These are aimed at integrations that are able to upgrade in a timely manner once the full version of the API is released. Expected lifetime of a release candidate is at most 2 months from the release of the major version it was developed for. As noted above, the prior version will continue to receive support for at least 12 months.

V1+ Basics

The sections below outline some of the basic functionality common to all V1+ versions of the API.

Standard JSON Responses

Every response from the API (with the exception of PDF downloads in V2+) have a standard set of information:

• api_version - The major version number for the API.(e.g. 2)
• source - The endpoint that produced the response (e.g. GET /api/v2/plans)
• time - The time the response was generated in UTC (e.g. 2021-04-16T11:31:28-07:00)
• code - The HTTP status code (e.g. 200)
• message - The human readable equivalent to the HTTP status code (e.g. Unauthorized)
• total_items - The total number of results. In situations where there are multiple results, this number can be greater than the number of items returned (See the pagination section below)
• items - The array of results. This will be an array even if an endpoint will only return a single result.
• errors - An array of detailed error messages (e.g. [title cannot be blank, unknown contributor role]).

API Errors

If the access token used to make the request is no longer valid an HTTP 401 UNAUTHORIZED message will be returned along with the following JSON response. In this situation the ApiClient should attempt to acquire a new access token (see above).

{
  "api_version": 2,
  "source": "GET /api/v2/plans",
  "time": "2021-04-16T11:31:28-07:00",
  "code": 401,
  "message": "Unauthorized",
  "total_items": 0,
  "items": [

  ],
  "errors": [
    "token is invalid, expired or has been revoked"
  ]
}

In situations where the requested item does not exist or the access token does not have permission to access the item, an HTTP 404 NOT FOUND is returned along with the following JSON:

{ 
  "application": "dmptool-dev",
  "source": "GET /api/v2/plans/123",
  "time": "2020-02-07T14:04:01-07:00",
  "caller": "my_api_client",
  "code": 404,
  "message": "NOT FOUND", 
  "total_items": 0, 
  "items": [],
  "errors": ["plan could not be found"],
}

In the event that a fatal error is thrown from any of the API endpoints an HTTP 500 INTERNAL SERVER ERROR will be returned along with the following JSON body:

{  
  "application": "dmptool-dev",
  "source": "GET /api/v2/plans/",
  "time": "2020-02-07T14:04:01-07:00",
  "caller": "my_api_client",
  "code": 500,
  "message": "INTERNAL SERVER ERROR", 
  "total_items": 0, 
  "items": [],
  "errors": [], 
}

The DMPPTool administrator will need to check your logs to determine the root cause of these fatal errors.

Pagination

By default all endpoints allow for pagination. You can specify the default and maximum allowable per_page in your config/initializers/dmproadmap.rb file.

The API Client can specify the page=[n] and per_page=[n] values in the query string when they call the endpoint.

The JSON response will contain useful links that the caller can use to step through the pages and retrieve the full set of information:

{
  "application": "dmptool-dev",
  "source": "GET /api/v2/templates",
  "time": "2020-02-07T14:04:01-07:00",
  "caller": "my_api_client",
  "code": 200,
  "message": "OK",
  "page": 2,
  "per_page": 20,
  "total_items": 58,
  "prev": "/api/v2/templates?page=1&per_page=20",
  "next": "/api/v2/templates?page=3&per_page=20",
  "items": [
    { "dmp_template": "..." },
    { "dmp_template": "..." }
  ]
}

V2+ Basics

Doorkeeper Configuration

The bulk of the OAuth/Doorkeeper configuration is contained within the config/initializers/doorkeeper.rb file. This file retains all of the default Doorkeeper entries (commented out) to make it easier in the future to review and customize. This file defines all of the rules that Doorkeeper will use when handling calls to the http://localhost:3000/oauth/ endpoints.

Some terminology:

• Application - Synonymous with API client, an external system that has been provided access to the API.
• Resource Owner - Synonymous with user, the individual user who has given authorization for the API client to access their data
• Scope - A tag that helps us define groups or levels of access. For example 'read_dmps' allows the caller to fetch the list of plans, single plans and download a plan PDF
• Grant Type - The type of access token being requested client_credentials or authorization_code in our situation.

The apps/controllers/api/v2/base_api_controller.rb has an initial authenticate_request callback that ensures that the Doorkeeper token was provided and is valid.

The individual controllers have callbacks that define which Scopes are required for authorization_code access tokens (aka on a user's behalf).

Each controller has a corresponding policy that is used to determine what results are returned based on the API client and the user (aka Resource Owner).

Tables:

• oauth_applications - The old api_clients table with additional columns specific to doorkeeper oauth
• oauth_grants - A table that stores the temporary authorization codes generated as part of the authorization_code workflow
• oauth_tokens - A table that stores the access tokens used by the API client

Authorization Code Scoping

Scopes provide us with a way to restrict what information an ApiClient is able to access on behalf of a User. An ApiClient must first be given permission to access specific scopes on the 'Api Clients' section of the UI. The API client must then specify the scopes they wish to access on behalf of the user when they request authorization. The user is presented with that list when they authorize the interaction.

The available scopes are:

• read_dmps - Allows the ApiClient to fetch the list of the user's plans, fetch a single plan, or download the PDF copy of a plan
• edit_dmps - Allows the API client to edit a user's plan (not yet implemented)
• create_dmps - Allows the API client to create a plan on the user's behalf. (not yet fully implemented - contributors and other data points are not added to the new plan)

Note that a user can revoke the authorization for an API client in its entirety. They cannot revoke individual scopes at this time.

Further Reading on OAuth

• Nice overview of how OAuth works
• Excellent overview of the different OAuth grant types
• Doorkeeper gem documentation