API Fetch DMP

API Overview

Fetching or downloading a single DMP

The DMPs you can fetch are determine 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). Note that you MUST specify scope=read_dmps in your request for an access token!

• Standard access (using grant_type=client_credentials):

  1. You are a researcher - you can retrieve your own DMPs or any publicly visible DMP See the DMPTool's public plans for examples
  2. You are an organizational administrator - you can fetch your own DMPs as well as any DMPs created by your users.

• Protected access (using grant_type=authorization_code):

  1. Allows you to fetch any "published" DMP (those that have been assigned a DMP ID) owned by the authorized user.

Example request to get the JSON metadata:

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

A PDF of the plan can be downloaded by using content negotiation. For example:

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

Note: For those using protected access Note that the JSON response will include a dmproadmap_privacy flag that informs of the authorized user's specified visibility setting for the DMP. While the user gave you permission to access their DMPs, we ask you to please adhere to their specified visibility policy when it comes to handling the DMP meatdata and/or PDF copy. The possible visibilities are: private, organizational, public. Please note that 'private' means they do not want to share the DMP and organizational means that they are willing to share the DMP with other members of their organization or research project team.

The fetch DMP API provides you with the DMP's metadata in the RDA common standard format v1.1. See below for an explanation of the non-standard attributes that are prefixed with dmproadmap_.

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

{
  "application": "dmptool-dev",
  "api_version": 2,
  "source": "GET /api/v2/plans/123",
  "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": 1,
  "items": [
    {
      "dmp": {
        "title": "My example DMP",
        "description": "<p>This is my example DMP's abstract.</p>\r\n<p>It contains a description of my plan.</p>",
        "language": "eng",
        "created": "2021-01-19T22:43:24Z",
        "modified": "2021-04-15T20:40:26Z",
        "ethical_issues_exist": "yes",
        "ethical_issues_description": "We will be potentially collecting personally identifiable information.",
        "ethical_issues_report": "http://example.org/policies/pii.html",
        "dmp_id": { "type": "doi", "identifier": "https://doi.org/10.48321/D1JS30" },
        "contact": {
          "name": "Jane Doe",
          "mbox": "jane.doe@example.edu",
          "affiliation": {
            "name": "Example University",
            "abbreviation": "EU",
            "affiliation_id": { "type": "ror", "identifier": "https://ror.org/00000000" }
          },
          "contact_id": { "type": "orcid", "identifier": "https://orcid.org/0000-0000-0000-000X" }
        },
        "contributor": [
          {
            "name": "Samantha Smith",
            "mbox": "samantha@another-example.edu",
            "role": ["http://credit.niso.org/contributor-roles/investigation"],
            "affiliation": {
              "name": "Another University",
              "abbreviation": "Other Uni",
              "affiliation_id": { "type": "ror", "identifier": "https://ror.org/00000000X" }
            },
            "contributor_id": { "type": "orcid", "identifier": "https://orcid.org/0000-0000-0000-000Y" }
          }
        ],
        "project": [
          {
            "title": "My example DMP",
            "description": "<p>This is my example DMP's abstract.</p>\r\n<p>It contains a description of my plan.</p>",
            "start": "2021-02-19T00:00:00Z",
            "end": "2021-12-10T00:00:00Z",
            "funding": [
              {
                "name": "National Funding Organization",
                "funder_id": { "type": "fundref", "identifier": "https://doi.org/10.13039/100000XXX" },
                "funding_status": "planned",
                "dmproadmap_funding_opportunity_id": { "type": "other", "identifier": "12345" },
                "dmproadmap_funded_affiliations": [
                  {
                    "name": "Example University",
                    "abbreviation": "EU"
                  }
                ]
              }
            ]
          }
        ],
        "dataset": [
          {
            "type": "dataset",
            "title": "My first test dataset",
            "description": "<p>This is going to be great!!!</p>",
            "personal_data": "unknown",
            "sensitive_data": "yes",
            "issued": "2022-05-13T00:00:00Z",
            "preservation_statement": "<strong>Question:</strong> Which data are of long-term value and should be retained, shared, and/or preserved?<br><strong>Answer:</strong> <p>I don't know.</p>\r\n<p>eebetbet</p><br><strong>Question:</strong> What is the long-term preservation plan for the dataset?<br><strong>Answer:</strong> <p>We will definitely do something.</p>\r\n<p>eebetbet</p>",
            "security_and_privacy": [
              {
                "title": "Ethics & privacy",
                "description": [
                  "<strong>Question:</strong> Will your project involve sensitive data? Examples include: <span style=\"font-weight: 400;\">traditional knowledge, archeological artifacts, endangered species, medical data, and human subject research.</span><br><strong>Answer:</strong> <p>Probably.</p>\r\n<p>Time will tell.</p>",
                  "<strong>Question:</strong> How will you manage access and security?<br><strong>Answer:</strong> <p>Very carefully.</p>",
                ]
              },
              {
                "title": "Storage & security",
                "description": [
                  "<strong>Question:</strong> Describe the planned quality assurance and back-up procedures, including security/storage and any use of encryption.<br><strong>Answer:</strong> <p>We will explain all of this later.</p>"
                ]
              }
            ],
            "data_quality_assurance": "<strong>Question:</strong> How will the data be collected or created?<br><strong>Answer:</strong> <p>Through various instruments.</p><br><strong>Question:</strong> What standards and methodologies will be utilized for data collection and management?<br><strong>Answer:</strong> <p>Only the best.</p>",
            "dataset_id": { "type": "other", "identifier": "1" },
            "distribution": [
              {
                "title": "Anticipated distribution for My first test dataset",
                "byte_size": 60129542144,
                "data_access": "open",
                "host": {
                  "title": "Example Repository",
                  "description": "The example repository is for DMPTool testing",
                  "url": "https://example.org/repo",
                  "dmproadmap_host_id": { "type": "url", "identifier": "https://www.re3data.org/api/v1/repository/r3d10000XXXX" }
                },
                "license": [
                  {
                    "license_ref": "http://spdx.org/licenses/Artistic-1.0.json",
                    "start_date": "2022-05-13T00:00:00Z"
                  }
                ]
              }
            ],
            "metadata": [
              {
                "description": "Dublin Core - A basic, domain-agnostic standard which can be easily understood ...",
                "metadata_standard_id": { "type": "url", "identifier": "https://rdamsc.bath.ac.uk/api2/m15" }
              }
            ],
            "technical_resource": []
          }
        ],
        "dmproadmap_template": { "id": 1, "title": "Digital Curation Centre (DCC) Template" },
        "dmproadmap_related_identifiers": [
          { "type": "doi", "identifier": "http://doi.org/10.1234/ABC987.de65", "descriptor": "is_supplement_to" }
        ],
        "dmproadmap_privacy": "private",
        "dmproadmap_links": {
          "get": "http://dmptool.org/api/v2/plans/123",
          "download": "http://dmptool.org/api/v2/plans/123.pdf"
        },
        "dmproadmap_external_system_identifier": "https://your.site.edu/path/12345",
        "dmproadmap_sponsors":[
          { "name":"Example University", "sponsor_id": { "type":"ror","identifier":"https://ror.org/abcdefghij" } }
        ]
      }
    }
  ]
}

Explanation of the non-RDA common standard attributes contained in the JSON response:

• dmproadmap_funding_opportunity_id - The identifier for the Funder's call for grant proposals
• dmproadmap_funded_affiliations - There are potentially multiple contributors from multiple institutions identified on a DMP. This array contains the ones associated with the owners and co-owners of the DMP.
• dmproadmap_host_id - The re3data id for the repository the user specified
• dmproadmap_template - The DMP template the DMP was derived from
• dmproadmap_related_identifiers - Any known related identifiers (e.g. datasets, journal articles, other DMPs, etc.)
• dmproadmap_privacy - The user's specified visibility for the DMP (e.g. private, organizational or public)
• dmproadmap_links - Helpful links to re-fetch the DMP or download the PDF version.
• dmproadmap_external_system_identifier - The identifier for your system (if you created the DMP via the API and provided a "dmp_id":{"type":"your_system","identifier":"122345"}
• dmproadmap_sponsors - Organizations that sponsor the research project in some way (e.g. a field station or lab where research activities will be performed)