-
Notifications
You must be signed in to change notification settings - Fork 13
API V0 Documentation
The API currently provides statistical information and a full text API that allows you to view your users' plans. The API is only open to organizational administrators. 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 your requests to the API. The API will always respond with JSON.
This is documentation is for the original version of the DMPTool API (version 0). If you are interested in the latest version of the API (version 1+) then please see the API overview documentation
For all api calls, the following headers are expected:
- “Authorization:Token token=<API_TOKEN>”
- "Content-Type: application/json"
In the first, the <API_TOKEN> is found on your 'edit profile' page, as mentioned above. This token is used to authenticate the user, and determine what data will be returned. If the edit profile page does not display your API token, please contact us to have one generated for you.
Please do NOT share your API token with others!
For example:
> curl -vL -H"Authorization:Token token=myUniqueToken, Content-Type:application/json" https://dmptool.org/api/v0/statistics/users_joined| 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 | 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 dates of the form YYYY-MM-DD, for example, 2017-04-01. Arguments accepted are:
- start_date
- end_date
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>
},
{...}
]
}This API method returns metadata on all plans created by users of your organisation. This can be used to generate other statistics. The return format is:
{
"plans": [
{
"id": <integer>,
"grant_number": <integer>,
"title": <string>,
"template": {
"title": <string>,
"id": <integer>
},
"funder": {
"name": <string>
},
"principal_investigator": {
"name": <string>
},
"data_contact": {
"info": <string>
},
"description": <string>
},
{...}
]
}| Path | Method | Description |
|---|---|---|
/api/v0/plans |
GET | Returns your user's plans as JSON. |
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 do analysis of a large set of plans.
Note that this API pages its results 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,199 - specific users - Will only return the plans associated with the user ids you specify. For example
/api/v0/plans?user=15,1234 - specific plans - Will only return the plans matching the ids you specify. For example
/api/v0/plans?plan=15,16,78
Note that you can combine these filters. For example:
/api/v0/plans?template=184,199&created_after=2019-10-01
[
{
"id": 71,
"title": "Sample plan",
"grant_number": null,
"last_updated": "2019-09-15 22:30:42 UTC",
"creation_date": "2019-09-02 22:21:30 UTC",
"template": {
"title": "NSF-GEN: Generic",
"id": 1874
},
"funder": {
"name": "National Science Foundation (NSF)"
},
"principal_investigator": {
"name": null,
"email": null,
"phone": null
},
"data_contact": {
"name": null,
"email": null,
"phone": null
},
"users": [
{
"email": "[email protected]"
}
],
"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?"
}
}
]
}
]
}
]
}
]