API v2 Documentation
This version of the DMPRoadmap API allows users to authorize third-party applications to access the user's resources in DMPRoadmap. This API complies with the RDA Common Standard Metadata schema v1.0. This is a metadata standard for data management plans that was established by the Research Data Alliance.
All endpoints in this API are relative to the following base URL:
https://example.com
For example:
https://example.com/api/v2/heartbeat
Most endpoints require an OAuth 2.0 access token provided as a Bearer token in the Authorization header.
Example:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://example.com/api/v2/plans"(Only the /api/v2/heartbeat endpoint does not require authentication.)
Third-party applications that need to authenticate users programmatically should consult OAuth 2.0 Authentication.
Typically, the representatives of a third-party application will approach and ask to register their application in the system. And with their application registered, a user who has an account in both systems will be able to pull their resources from DMPRoadmap into the third-party application.
To register a third-party application, a request must be made to the DMPRoadmap service team to enable the application from their administrative functions.
Use the examples below to quickly verify connectivity and authentication.
Check service availability:
curl "https://example.com/api/v2/heartbeat"Fetch your profile (requires a valid access token):
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://example.com/api/v2/me"List your accessible plans:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://example.com/api/v2/plans"The API requests that return lists are paginated. The maximum number of items in a page is 100. Thus, the pagination parameters are the following:
| Name | Description | Example |
|---|---|---|
| page | Sets the page number | page=3 |
| per_page | Sets the number of items per page (maximum 100). | per_page=100 |
This endpoint does not require authentication because its sole purpose is to confirm to prospective clients that the API is up and running.
GET /api/v2/heartbeat
| Method | Path | Description |
|---|---|---|
| GET | /api/v2/heartbeat | Returns confirmation that the API is up and running. |
None
| Code | Description |
|---|---|
| 200 | OK |
curl "https://example.com/api/v2/heartbeat"{
"application": "DMPRoadmap",
"source": "GET /api/v2/heartbeat",
"time": "2020-02-13T19:47:04-07:00",
"caller": "YOUR_OAUTH_APP",
"code": 200,
"message": "OK",
"total_items": 0,
"items": []
}GET /api/v2/me
| Method | Path | Description |
|---|---|---|
| GET | /api/v2/me | Returns the profile info of the resource owner associated with the access token. |
None
| Code | Description |
|---|---|
| 200 | OK |
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://example.com/api/v2/me"{
"firstname": "DMP",
"surname": "Administrator",
"email": "dittest@ualberta.ca",
"organisation": "Digital Research Alliance of Canada",
"language": "English (CA)"
}The /api/v2/plans endpoint currently supports only the Authorization Code Grant (ACG) flow and returns plans where the user has an active role.
We are working on a new feature where users must verify that they are a member of an organisation (using SSO) before switching to that organisation in DMPRoadmap. Once this feature is in place, the /api/v2/plans endpoint can be updated to include plans shared with the user's organisation in DMPRoadmap.
In addition, we will be developing support for the Client Credentials (CC) flow in the v2 API. That flow will be for organisational admins (whereas the ACG flow is for standard users), so org-admins will be able to retrieve their own plans (that is, plans where they have an active role) as well as their organisation's plans in DMPRoadmap.
GET /api/v2/plans
| Method | Path | Description |
|---|---|---|
| GET | /api/v2/plans | Returns the plans that the resource owner has access to. |
A flag titled complete can be included as ?complete=true to form the endpoint /api/v2/plans?complete=true. This returns all questions and answers for all plans. It defaults to false and is therefore compliant with the RDA metadata standard, but can be passed with a value of true to include plan questions and answers.
| Code | Description |
|---|---|
| 200 | OK |
Retrieve all resource owner plans:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://example.com/api/v2/plans"Retrieve all resource owner plans, including all questions and answers:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://example.com/api/v2/plans?complete=true"{
"application": "DMPRoadmap",
"source": "GET /api/v2/plans",
"time": "2020-06-11T15:32:04-07:00",
"caller": "YOUR_OAUTH_APP",
"code": 200,
"message": "OK",
"page": 1,
"per_page": 20,
"total_items": 248,
"next": "/api/v2/plans?page=2&per_page=20",
"items": [
{
"dmp": {
"schema": "https://github.com/RDA-DMP-Common/RDA-DMP-Common-Standard/tree/master/examples/JSON/JSON-schema/1.0",
"title": "USGS CDR/ECV DMP",
"language": "eng",
"created": "2013-01-07T19:06:11Z",
"modified": "2020-04-27T22:38:23Z",
"ethical_issues_exist": "unknown",
"dmp_id": {
"type": "url",
"identifier": "http://localhost:3000/api/v2/plans/5119"
},
"contact": {
"name": "Jane Doe",
"mbox": "jane.doe@example.org",
"affiliation": {
"name": "Example University",
"abbreviation": "EU",
"affiliation_id": {
"type": "ror",
"identifier": "https://ror.org/124abc0000a"
}
}
}
}
}
]
}GET /api/v2/plans/:id
| Method | Path | Description |
|---|---|---|
| GET | /api/v2/plans/:id | Returns the plan with the specified id. |
This endpoint will also support the ?complete=true flag, which will return all questions and answers to the plan with the specified id.
| Code | Description |
|---|---|
| 200 | OK |
Retrieve a plan:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://example.com/api/v2/plans/123"Retrieve a plan, including all questions and answers:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://example.com/api/v2/plans/123?complete=true"{
"application": "DMPRoadmap",
"source": "GET /api/v2/plans/123",
"time": "2020-02-07 14:04:01 UTC",
"caller": "YOUR_OAUTH_APP",
"code": 200,
"message": "OK",
"total_items": 1,
"items": [
{
"dmp": {
"schema": "https://github.com/RDA-DMP-Common/RDA-DMP-Common-Standard/tree/master/examples/JSON/JSON-schema/1.0",
"title": "Examination of some interesting topics in biochemistry",
"language": "eng",
"created": "2019-08-19T15:45:07Z",
"modified": "2020-04-24T22:28:22Z",
"ethical_issues_exist": "unknown",
"dmp_id": {
"type": "url",
"identifier": "http://localhost:3000/api/v2/plans/123"
},
"contact": {
"name": "Jane Doe",
"mbox": "jane.doe@example.edu",
"affiliation": {
"name": "Example University",
"abbreviation": "EU",
"affiliation_id": {
"type": "ror",
"identifier": "https://ror.org/124abc0000a"
}
},
"contact_id": {
"type": "orcid",
"identifier": "0000-0000-0000-0000"
}
},
"contributor": [
{
"name": "John Smith",
"mbox": "john.smith@un.edu",
"role": [
"https://dictionary.casrai.org/Contributor_Roles/Data_curation",
"https://dictionary.casrai.org/Contributor_Roles/Investigation"
],
"affiliation": {
"name": "University of Nowhere",
"abbreviation": "UofN",
"affiliation_id": {
"type": "ror",
"identifier": "https://ror.org/123abc45y"
}
},
"contributor_id": {
"type": "orcid",
"identifier": "https://orcid.org/0000-0000-0000-0000"
}
}
],
"project": [
{
"title": "Examination of some interesting topics in biochemistry"
}
],
"dataset": [
{
"title": "DMP Dataset",
"personal_data": "unknown",
"sensitive_data": "unknown",
"dataset_id": {
"type": "url",
"identifier": "http://localhost:3000/api/v2/plans/123"
},
"distribution": [
{
"title": "PDF - Testing our maDMP JSON export",
"data_access": "open",
"download_url": "http://localhost:3000/plans/123/export.pdf",
"format": [
"application/pdf"
]
}
]
}
],
"extension": [
{
"dmproadmap": {
"template": {
"id": 437,
"title": "EF - Biochemistry"
}
}
}
]
}
}
]
}GET /api/v2/templates
| Method | Path | Description |
|---|---|---|
| GET | /api/v2/templates | Returns a list of all templates accessible by the resource owner sorted by organisation. |
None
| Code | Description |
|---|---|
| 200 | OK |
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://example.com/api/v2/templates"{
"application": "DMPRoadmap",
"source": "GET /api/v2/templates",
"time": "2020-05-13T22:23:29-07:00",
"caller": "YOUR_OAUTH_APP",
"code": 200,
"message": "OK",
"page": 1,
"per_page": 20,
"total_items": 38,
"next": "/api/v2/templates?page=2&per_page=20",
"items": [
{
"dmp_template": {
"title": "EF - Biochemistry",
"description": "A biochemistry template for the Example Funder",
"version": 3,
"created": "2018-02-13T07:18:08Z",
"modified": "2018-04-18T18:18:36Z",
"affiliation": {
"name": "Example Funder",
"abbreviation": "EF",
"affiliation_id": {
"type": "ror",
"identifier": "https://ror.org/000aaa0000"
}
},
"template_id": {
"type": "other",
"identifier": "437"
},
"questions": [
{
"question_id": 68954,
"text": "Which RDC datasets will be used in the research?"
}
]
}
}
]
}GET /api/v2/templates/:id
| Method | Path | Description |
|---|---|---|
| GET | /api/v2/templates/:id | Returns the template with the specified id. |
None
| Code | Description |
|---|---|
| 200 | OK |
| 404 | Not Found |
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" "https://example.com/api/v2/templates/437"{
"application": "DMPRoadmap",
"source": "GET /api/v2/templates/437",
"time": "2020-05-13T22:23:29-07:00",
"caller": "YOUR_OAUTH_APP",
"code": 200,
"message": "OK",
"total_items": 1,
"items": [
{
"dmp_template": {
"title": "EF - Biochemistry",
"description": "A biochemistry template for the Example Funder",
"version": 3,
"created": "2018-02-13T07:18:08Z",
"modified": "2018-04-18T18:18:36Z",
"affiliation": {
"name": "Example Funder",
"abbreviation": "EF",
"affiliation_id": {
"type": "ror",
"identifier": "https://ror.org/000aaa0000"
}
},
"template_id": {
"type": "other",
"identifier": "437"
},
"questions": [
{
"question_id": 68954,
"text": "Which RDC datasets will be used in the research?"
}
]
}
}
]
}{
"application": "DMPRoadmap",
"source": "GET /api/v2/templates/999999",
"time": "2025-05-13T22:23:29-07:00",
"caller": "YOUR_OAUTH_APP",
"code": 404,
"message": "NOT FOUND",
"total_items": 0,
"items": [],
"errors": ["Template not found"]
} |
 |