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. Version 0
2. Version 1+
3. Versioning Policy
4. Standard JSON Responses (V1+)
5. API Errors (V1+)
6. Pagination (V1+)

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

Version 1+

These 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]).

c

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": "..." }
  ]
}