API DMP List

API Overview

The DMP list API provides you with a summary of DMPs that can then be used to fetch the full metadata for a DMP or download it's PDF via the fetch a single DMP endpoint.

The DMPs that will be returned relies largely on the access scenario you are using and your role within the DMPTool (see the authentication section for an explanation of the different access scenarios).

• Standard access (using grant_type=client_credentials):

  1. You are a researcher - you will receive the full list of your DMPs.
  2. You are an organizational administrator - you will receive the full list of your own DMPs as well as any DMPs created by your users.

• Protected access (using grant_type=authorization_code):

  1. Returns the full list of "published" DMPs (those that have been assigned a DMP ID) owned by the authorized user.

Note: Plans are only available via the API if they are NOT designated as a "mock project for testing, practice, or educational purposes" on the Project Details tab and at least 50% of the questions have been answered.

You may include an scope flag in the request that will accept a value of mine, public or both (mine is the default). This flag is only applicable to the standard access mode. The different flag options will return:

• mine - The DMPs outlined above based on your role within the DMPTool
• public - All publicly visible DMPs. See the DMPTool's public plans for examples
• both - All publicly visible DMPs as well as the ones that would be returned when specifying mine

Example request:

curl -v https://dmptool.org/api/v2/plans \
  -H "Accept: application/json" \
  -H "Authorization: Bearer MY_ACCESS_TOKEN"

Example successful responses return an HTTP 200 OK (truncated to display one record):

{
  "application": "dmptool-dev",
  "api_version": 2,
  "source": "GET /api/v2/plans",
  "time": "2021-04-16T09:43:16-07:00",
  "caller": "your_email OR your_application_name",
  "code": 200,
  "message": "OK",
  "page": 1,
  "per_page": 20,
  "total_items": 6,
  "items": [
    { 
      "dmp": {
        "title": "Example DMP",
        "description": "This is the example DMP's abstract.",
        "language": "eng",
        "created": "2018-04-09T23:10:14Z",
        "modified": "2020-11-24T19:13:24Z",
        "ethical_issues_exist": "unknown",
        "dmp_id": { "type": "url", "identifier": "http://doi.org/10.1234/AB12CD.34" },
        "contact": {
          "name": "Jane Doe",
          "mbox": "[email protected]",
          "dmproadmap_affiliation": {
            "name": "Example University",
            "abbreviation": "EUniv.",
            "affiliation_id": { "type": "ror", "identifier": "https://ror.org/00000XX" }
          },
          "contact_id": { "type": "orcid", "identifier": "https://orcid.org/0000-0000-0000-0000" }
        },
        "dmproadmap_links": { 
          "get": "http://dmptool.org/api/v2/plans/123",
          "download": "http://dmptool.org/api/v2/plans/123.pdf" 
        }
      }
    }
  ]
}

Note that the above example only shows a single DMP record. An actual response would contain the a number of DMP records as specified by the per_page attribute. Please refer to the section on API pagination for more information.

Some public DMPs predate the assignment of DMP IDs. In these situations, the dmp_id attribute returned in the JSON will be the same as the dmproadmap_links - get URL.

For examples of error responses that you may receive, please see the section on API Errors