API v0 Documentation
The API currently has 5 endpoints: Plans, Guidance, Templates, Departments and Statistics. In order to use the API, permissions for each endpoint must be given to your organization, and an API token must display on your 'Edit Profile' page. This token is used to authenticate, and is passed through as an Authorization Token header in calls made to the API. The API will always respond in JSON, and arguments to the Plans endpoint will also be in JSON.
- Quick Guide on How to Use API V0
- Base Url & Request Urls
- Shared Headers
- Curl and Use of Escape characters
- Pagination
- Templates
- Guidance
- Plans
- Departments
- Statistics
- API Use Cases
The base url <BASE_URL> is the url of the Roadmap tool login page, e.g.,
<BASE_URL> = http://localhost:3000/
<BASE_URL> = https://dmponline.dcc.ac.uk/
<BASE_URL> = https://dmptool.org/
The request url for all api calls <REQUEST_URL> will be a combination of the <BASE_URL> and the api route with optional parameters,
<REQUEST_URL> = <BASE_URL>/<API_ROUTE>?
e.g.,
http://localhost:3000/api/v0/templates
https://dmponline.dcc.ac.uk/api/v0/plans?page=1
For all api calls, the following headers are expected:
- “Authorization:Token token=<API_TOKEN>”
- "Content-Type: application/json"
When you're granted the "Use API" privilege, the <API_TOKEN> is found on the 'Edit Profile' page. This is used to authenticate the user, and determine which API endpoints they have access to.
Using curl for API calls, in a shell like Bash, will require you to escape characters for "?" and "=" as follows "\?" and "\=" respectively, and "\" for at end of a line in a multiline line command, e.g.,
curl -H "Authorization:Token token=<API Token>" -H "Content-Type: application/json" \\
https://dmponline.dcc.ac.uk/api/v0/plans\?plan\=123456789
Please consult an online resource for escaping characters for the shell you are using.
API calls that return lists are paginated. The default size of the page is usually 10, and the max page size can be upto 100. A typical call will be of form
<REQUEST_URL_FOR_PAGINATION> = <BASE_URL>/<API_ROUTE>?&per_page=<UPTO 100>&page=<PAGE_NUMBER>&<OTHER_OPTIONS_OPTIONAL>
e.g., http://localhost:3000/api/v0/templates?&per_page=20&page=3
https://dmponline.dcc.ac.uk/api/v0/plans?&per_page=100&page=1&created_after=2019-01-01
| Command | Method | Route | Description |
|---|---|---|---|
| Index | GET | /api/v0/templates | Returns a list of all published templates, sorted by organization |
Format: <BASE_URL>/api/v0/templates
A call to this API Method will retrieve a list of all viewable DMPonline templates. The output will be in the following format:
{
"templates": [
{
“organisation_name”: <string>,
“organisation_id”: <integer>,
"is_funder": <boolean>,
“organisation_templates”: [
{
“title”: <string>,
“id”: <integer>,
"description": <string>,
},
{...},
],
"customized_templates": [
{
"title": <string>,
"id": <integer>,
"customization_of": <integer>,
"description": <string>,
},
{...},
],
},
{...}
]
}| Command | Method | Route | Description |
|---|---|---|---|
| Index | GET | /api/v0/guidances | Returns a list of all guidances for your organisation, and the managing organisation, sorted by guidance group |
Format: <BASE_URL>/api/v0/guidances
A call to this API method will return a list of all viewable guidances. These will include your organisation's guidance, and any public guidance within the tool. The guidance entries are sorted by guidance_group, and include information about the theme for a given guidance. The response data will be in the following format:
{
"guidance_groups": [
{
"name": <string>,
"id": <integer>,
"optional": <boolean>,
"updated": <datetime>,
"guidances": [
{
"text": <string>,
"updated": <datetime>,
"themes": [
{
"title": <string>
},
{...}
]
},
{...}
]
},
{...}
]
}| Path | Method | Description |
|---|---|---|
/api/v0/plans |
GET | Returns your user's plans as JSON. |
Format: <BASE_URL>/api/v0/plans
This API allows you to retrieve your user's plans as a JSON file so that you can import aspects of the plan into local research data management systems or conduct analysis on a large set of plans.
Note that this API returns the results in pages and can only return 100 plans per request. To retrieve anything beyond the first 100 plans you will need to specify a page. For example: /api/v0/plans?page=2
You can filter the results of this API by passing along date restrictions:
- created_after - Will only returns plans created after the specified date. For example
/api/v0/plans?created_after=2019-01-01 - created_before - Will only returns plans created before the specified date. For example
/api/v0/plans?created_before=2019-01-01 - updated_after - Will only returns plans updated after the specified date. For example
/api/v0/plans? updated_after =2019-01-01 - updated_before - Will only returns plans updated before the specified date. For example
/api/v0/plans? updated_before =2019-01-01
You can also filter the results by passing along any combination of the following:
- specific templates - Will only return the plans matching the template ids you specify. For example
/api/v0/plans?template=184 - specific users - Will only return the plans associated with the user ids you specify. For example
/api/v0/plans?user=15 - specific plans - Will only return the plans matching the ids you specify. For example
/api/v0/plans?plan=15
With any of these last three keys, you can instead express multiple of the same key by appending [] to the key. For example /api/v0/plans?user[]=15&user[]=16&user=[78]
Note that you can combine these filters. For example:
/api/v0/plans?template[]=187&template[]=199&created_after=2019-10-01
[
{
"id": 71,
"title": "Sample plan",
"grant_number": null,
"last_updated": "2019-10-15 22:30:42 UTC",
"creation_date": "2019-10-02 22:21:30 UTC",
"template": {
"title": "NSF-GEN: Generic",
"id": 187
},
"funder": {
"name": "National Science Foundation (NSF)"
},
"principal_investigator": {
"name": null,
"email": null,
"phone": null
},
"data_contact": {
"name": null,
"email": null,
"phone": null
},
"users": [
{
"email": "tester@example.org"
}
],
"description": null,
"plan_content": [
{
"title": "Data Management Plan",
"description": null,
"sections": [
{
"title": "Types of data produced",
"description": null,
"number": 1,
"questions": [
{
"text": "<p>Types of data, samples, physical collections, software, curriculum materials, and other materials to be produced in the course of the project.</p>",
"number": 1,
"format": "Text area",
"option_based": false,
"themes": [
{
"theme": "Data collection"
}
],
"answered": true,
"answer": {
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed fringilla ante eget lacus semper nec fermentum dolor lacinia. Cras ac risus sit amet eros faucibus fermentum nec at leo? Cras metus augue, vestibulum sit amet interdum in, semper in augue. Etiam nec laoreet dolor! Proin congue risus id leo vehicula semper. Suspendisse congue lectus ac libero condimentum pharetra? Etiam tortor nulla; bibendum condimentum ultrices vel, lacinia id nibh. Duis varius bibendum nisl, ut dictum odio hendrerit nec. In est ligula, egestas eu pretium id; euismod vel enim. Donec dapibus laoreet magna at euismod. Curabitur ipsum quam, placerat vel convallis id, ultrices eget enim. Phasellus ipsum lacus; placerat tincidunt dignissim ut, vulputate vel felis. Donec libero enim, lacinia faucibus adipiscing non; fermentum vitae turpis. Phasellus sed feugiat nisi?"
}
}
]
},
{
"title": "Data and metadata standards ",
"description": null,
"number": 2,
"questions": [
{
"text": "<p>Standards to be used for data and metadata format and content (where existing standards are absent or deemed inadequate, this should be documented along with any proposed solutions or remedies).</p>",
"number": 1,
"format": "Text area",
"option_based": false,
"themes": [
{
"theme": "Data format"
},
{
"theme": "Metadata & documentation"
}
],
"answered": true,
"answer": {
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed fringilla ante eget lacus semper nec fermentum dolor lacinia. Cras ac risus sit amet eros faucibus fermentum nec at leo? Cras metus augue, vestibulum sit amet interdum in, semper in augue. Etiam nec laoreet dolor! Proin congue risus id leo vehicula semper. Suspendisse congue lectus ac libero condimentum pharetra? Etiam tortor nulla; bibendum condimentum ultrices vel, lacinia id nibh. Duis varius bibendum nisl, ut dictum odio hendrerit nec. In est ligula, egestas eu pretium id; euismod vel enim. Donec dapibus laoreet magna at euismod. Curabitur ipsum quam, placerat vel convallis id, ultrices eget enim. Phasellus ipsum lacus; placerat tincidunt dignissim ut, vulputate vel felis. Donec libero enim, lacinia faucibus adipiscing non; fermentum vitae turpis. Phasellus sed feugiat nisi?"
}
}
]
}
]
}
]
}
]| Command | Method | Route | Description |
|---|---|---|---|
| Create | POST | /api/v0/plans | Allows for the creation of a new plan based on passed parameters |
Format: <BASE_URL>/api/v0/plans
A call to this API method will result in the creation of a new plan according to the arguments passed in the request body. The format of the arguments in the request body is JSON. The "template_id" field takes in the id of one of the templates, which will be viewable from the Templates/index API method. The title will be the title given to the plan. The email passed, if a user exists on the tool with that email, will be used to determine the owner of the newly created plan. That user must be from the same organisation as the one using the API, or an error will be generated. If there is no user on the tool with that email, the plan will be created, and and invitation email will be generated and sent to them. The request body takes the following form:
{
"template_id": <integer>,
"plan":{
"title": <string>,
"email": <string>
}
}The response to this call will return some metadata about the newly created plan:
{
"plan": {
"title": <string>,
"template": <string>,
"created_by": <string>,
"id": <integer>,
"created_at": <datetime>
}
}| Command | Method | Route | Description |
|---|---|---|---|
| departments | GET | /api/v0/departments | The list of your organization's departments |
| departments_users | GET | /api/v0/departments/users | The list of users by department |
| assign_users | PATCH | /api/v0/departments/:id/assign_users | Attaches the specified users to the department |
| unassign_users | PATCH | /api/v0/departments/:id/unassign_users | Detaches the specified users from the department |
The departments endpoint allows you to perform batch updates that can assign or unassign users from your departments.
Format: <BASE_URL>/api/v0/departments
<BASE_URL>/api/v0/departments/users
<BASE_URL>/api/v0/departments/:id/assign_users
<BASE_URL>/api/v0/departments/:id/unassign_users
This API endpoint returns the list of your organization's departments. You should use the 'id' when assigning/unassigning users in subsequent calls to the other methods.
[
{
"code": <string>,
"name": <string>,
"id": <integer>
}
]This API endpoint will return a list of departments and the users (email address) currently associated with those departments. All users who are not assigned to a specific department appear in the section with a department id of 'null'
[
{
"code": <string>,
"name": <string>,
"id": <integer>,
"users": [
{
"email": <string>
}
]
},
{
"code": null,
"name": null,
"id": null,
"users": [
{
"email": <string>
}
]
}
]This endpoint will assign all of the users you specify (by email address) to the department identified (by id) in the URL. It expects the following JSON body:
{
"users" : [
<string>,
<string>
]
}and returns the updated list of departments and users (see the 'Department Users' section above)
This endpoint will unassign all of the users you specify (by email address) from the department identified (by id) in the URL. It expects the following JSON body:
{
"users" : [
<string>,
<string>
]
}and returns the updated list of departments and users (see the 'Department Users' section above)
| Command | Method | Route | Description |
|---|---|---|---|
| users_joined | GET | /api/v0/statistics/users_joined | Number of users who have joined your organisation |
| using_template | GET | /api/v0/statistics/using_template | Number of plans based off of un-customized templates your organisation has created |
| plans_by_template | GET | /api/v0/statistics/plans_by_template | Number of plans created by your organisation's users, sorted by template |
| plans | GET | /api/v0/statistics/plans | Generic metadata about all plans created by all users from your organisation |
All methods from the statistics endpoint will take additional arguments as query string in order to limit the dates between which the statistic is calculated. Two arguments are accepted, both in the format of YYYY-MM-DD, for example, 2017-04-01. Arguments accepted are:
- start_date
- end_date
Format: <BASE_URL>/api/v0/statistics/users_joined
<BASE_URL>/api/v0/statistics/using_template
<BASE_URL>/api/v0/statistics/plans_by_template/
<BASE_URL>api/v0/statistics/plans
This API method returns the number of users who have joined your organisation. Return format is:
{
"users_joined": <integer>
}This API method returns the number of plans created, by any user of the tool, based on templates created by your organisation. The return format is:
{
"templates": [
{
"template_name": <string>
"template_id": <integer>
"template_uses": <integer>
},
{...}
]
}This API method returns the number of plans created, by users of your organisation, ordered by template. The return format is:
{
"templates": [
{
"template_name": <string>
"template_id": <integer>
"template_uses": <integer>
},
{...}
]
}Follow the link to view use cases: https://github.com/DMPRoadmap/roadmap/wiki/API-use-cases
 |
 |