API v2 Documentation

DMPRoadmap API - Version 2

This version of the DMPRoadmap API allows users to authorize third-party applications to access the user's resources in dmp_assistant. 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.

Table of Contents

1. Registering a client application in the system
2. Pagination
3. Endpoints
4. Templates
5. Guidances
6. Departments
7. Statistics

Registering a client application in the system

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 DMP Assistant service team to enable the application from their administrative functions.

Pagination

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

Endpoints

Heartbeat

This endpoint does not require any authentication to make requests to as 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.

Parameters

None

Responses

Code	Description
200	OK

Example value

{ 
 "application": "DMPRoadmap", 
 "source": "GET /api/v2/heartbeat", 
 "time": "2020-02-13T19:47:04-07:00", 
 "caller": "::1", 
 "code": 200, 
 "message": "OK", 
 "total_items": 0, 
 "items": [] 
} 

Me

GET /api/v2/me

Method	Path	Description
GET	/api/v2/me	Returns the profile info of the resource owner associated with the access token.

Parameters

None

Responses

Code	Description
200	OK

Example value

{ 
 "id":106417, 
 "firstname":"FIRST_NAME", 
 "surname":"SURNAME", 
 "email":"name@example.com", 
 "created_at":"2023-01-04T22:00:32.697Z", 
 "updated_at":"2024-08-14T08:43:13.829Z", 
 "other_organisation":null, 
 "accept_terms":true, 
 "org_id":111111111, 
 "api_token":"Xxxxxxxxxxxxxxxxxxx", 
 "language_id":1, 
 "recovery_email":null, 
 "active":true, 
 "department_id":null, 
 "last_api_access":"2024-01-18T21:30:03.938Z", 
 "prefs":null 
} 

Plans

We have updated the design of the /api/v2/plans endpoint, which only supports the Authorization Code Grant (ACG) flow at the time of writing (2025-01-30), so that it is only the plans that the user has an active role with that are returned.

However, we are working on a new feature such that a user will have to verify that they are a member of an organisation (using SSO) before they can switch to the organisation in DMP Assistant. Once this new feature is in place, we can update the /api/v2/plans endpoint so that the plans shared with the user's organisation in DMP Assistant are also returned in the response.

In addition, we will also 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) and so we will ensure that org-admins will be able to retrieve their own plans (i.e. plans they have an active role with) as well as the plans of their organisation in DMP Assistant.

GET /api/v2/plans

Method	Path	Description
GET	/api/v2/plans	Returns the plans that the resource owner has access to.

Parameters

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 of all plans. It defaults to false and thereby is compliant with the RDA metadata standard, but can be passed in with a value of true to include the questions and answers of the plan.

Responses

Code	Description
200	OK

Example value

{ 
 "application": "DMPRoadmap", 
 "source": "GET /api/v2/plans", 
 "time": "2020-06-11T15:32:04-07:00", 
 "caller": "User/ApiClient name", 
 "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-CommonStandard/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.

Parameters

This endpoint will also support the ?complete=TRUE flag, which will return all questions and answers to the plan with the specified id.

Responses

Code	Description
200	OK

Example value

{
 "application": "DMPRoadmap", 
 "source": "GET /api/v2/plans/123", 
 "time": "2020-02-07 14:04:01 UTC", 
 "caller": "User/ApiClient name", 
 "code": 200, 
 "message": "OK", 
 "total_items": 1, 
 "items": [{ 
 "dmp": { 
 "schema": "https://github.com/RDA-DMP-Common/RDA-DMP-Common Standard/tree/master/examples/JSON/JSSON-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" 
 } 
 } 
 } 
 ] 
 } 
 }] 
} 

POST /api/v2/plans

Method	Path	Description
POST	/api/v2/plans	Creates a plan with the details specified in the body of the request.

Parameters

None

Body

Example of minimum body required

{ 
 "total_items": 1, 
 "items": [{ 
 "dmp": { 
 "title": "Examination of some interesting topics in biochemistry",  "contact": { 
 "mbox": "jane.doe@example.edu" 
 } 
 } 
 }] 
} 

Example of body with more data

{ 
 "total_items": 1, 
 "items": [{ 
 "dmp": { 
 "title": "Examination of some interesting topics in biochemistry",  "contact": { 
 "name": "Jane Doe", 
 "mbox": "jane.doe@example.edu", 
 "affiliation": { 
 "name": "Example University" 
 }, 
 "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", 
 "affiliation_id": { 
 "type": "ror", 
 "identifier": "https://ror.org/123abc45y" 
 } 
 }, 
 "contributor_id": { 
 "type": "orcid", 
 "identifier": "https://orcid.org/0000-0000-0000-0000"  }
 } 
 ], 
 "extension": [ 
 { 
 "dmproadmap": { 
 "template": { 
 "id": 3 
 } 
 } 
 } 
 ] 
 } 
 }] 
} 

Responses

Code	Description
201	Created

Example value

{ 
 "application": "DMPRoadmap", 
 "source": "POST /api/v1/plans/", 
 "time": "2020-02-07T14:04:01-07:00", 
 "caller": "User/ApiClient name", 
 "code": 201, 
 "message": "CREATED", 
 "total_items": 0, 
 "items": [{ 
 "dmp": "<< See an example of the full DMP JSON below in the 'Retrieve a Plan' section >>"  }], 
 "errors": [], 
} 

Templates

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.

Parameters

None

Responses

Code	Description
200	OK

Example value

{ 
 "application": "DMPRoadmap", 
 "source": "GET /api/v2/templates", 
 "time": "2020-05-13T22:23:29-07:00", 
 "caller": "your User/ApiClient name", 
 "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": "dmproadmap", 
 "identifier": "437" 
 } 
 } 
 } 
 ] 
}

Guidances

GET /api/v2/guidances

Method	Path	Description
GET	/api/v2/guidances	Returns a list of all guidances for the org-admin's organisation sorted by guidance group.

Parameters

None

Responses

Code	Description
200	OK

Schema

{ 
 "guidance_groups": [ 
 { 
 "name": <string>, 
 "id": <integer>, 
 "optional": <boolean>, 
 "updated": <datetime>, 
 "guidances": [ 
 { 
 "text": <string>, 
 "updated": <datetime>, 
 "themes": [ 
 { 
 "title": <string> 
 }, 
 {...} 
 ] 
 }, 
 {...} 
 ] 
 }, 
 {...} 
 ] 
}

Departments

GET /api/v2/departments

Method	Path	Description
GET	/api/v2/departments	Returns a list of the org-admin's organisation's departments.

Parameters

None

Responses

Code	Description
200	OK

Schema

[ 
 { 
 "code": <string>, 
 "name": <string>, 
 "id": <integer> 
 } 
] 

GET /api/v2/departments/users

Method	Path	Description
GET	/api/v2/departments/users	Returns a list of the org-admin's organisation's users by department.

Parameters

None

Responses

Code	Description
200	OK

Schema

[ 
 { 
 "code": <string>, 
 "name": <string>, 
 "id": <integer>, 
 "users": [ 
 { 
 "email": <string> 
 } 
 ] 
 }, 
 { 
 "code": null, 
 "name": null, 
 "id": null, 
 "users": [ 
 { 
 "email": <string> 
 } 
 ] 
 } 
] 

PATCH /api/v2/departments/:id/assign_users

Method	Path	Description
PATCH	/api/v2/departments/:id/assign_users	Assigns the specified users to the specified department.

Parameters

None

Schema

{ 
 "users" : [ 
 <string>, 
 <string> 
 ] 
} 

PATCH /api/v2/departments/:id/unassign_users

Method	Path	Description
PATCH	/api/v2/departments/:id/unassign_users	Unassigns the specified users from the specified department.

Parameters

None

Schema

{ 
 "users" : [ 
 <string>, 
 <string> 
 ] 
} 

Statistics

GET /api/v2/statistics/using_template

Method	Path	Description
GET	/api/v2/statistics/using_template	Returns the number of plans created, by any user of the tool, based on templates created by the org-admin's organisation

Parameters

Name	Description	Example
start_date	Filters for users that joined after the specified date.	start_date=2017-04- 01
end_date	Filters for users that joined before the specified date.	end_date=2018-04- 01

Responses

Code	Description
200	OK

Schema

{ 
 "templates": [ 
 { 
 "template_name": <string> 
 "template_id": <integer> 
 "template_uses": <integer> 
 }, 
 {...} 
 ] 
} 

GET /api/v2/statistics/plans_by_template

Method	Path	Description
GET	/api/v2/statistics/plans_by_template	Returns the number of plans created, by users of the org-admin's organisation, ordered by template.

Parameters

Name	Description	Example
start_date	Filters for users that joined after the specified date.	start_date=2017-04- 01
end_date	Filters for users that joined before the specified date.	end_date=2018-04- 01

Responses

Code	Description
200	OK

Schema

{ 
 "templates": [ 
 { 
 "template_name": <string> 
 "template_id": <integer> 
 "template_uses": <integer> 
 }, 
 {...} 
 ] 
} 

GET /api/v2/statistics/plans

Method	Path	Description
GET	/api/v2/statistics/plans	Returns generic metadata about all plans created by all users from the org admin's organisation.

Parameters

Name	Description	Example
start_date	Filters for users that joined after the specified date.	start_date=2017-04- 01
end_date	Filters for users that joined before the specified date.	end_date=2018-04- 01