API

stephaniesimms edited this page Sep 26, 2016 · 26 revisions

Basics

The DMPTool Restful API allows client software to retrieve a subset of DMPTool data by making HTTP requests to transfer JSON-encapsulated response data.

Note: The DMPTool team is currently gathering use cases and requirements to offer a more robust API to meet our users needs. Please feel free to submit your API needs to the DMPTool Github Issue Tracker or comment on the existing use cases.

Invoking the API

DMPTool2 API is accessible by any tool that is capable of making HTTP requests and receiving HTTP responses. As such, the API can be invoked from either the command line or from the browser, as well as client software applications.

For command line requests, you can use cURL. cURL is a tool for transferring data with URL syntax using the HTTP protocol. We provide cURL commands in this guide as examples. You can download cURL software if needed. The URLs in the examples can also be used in a browser.

For the browser, simply type the URL in the address bar to submit the request. We offer the following instructions as a guide:

  1. Log in to the DMPTool
  2. Paste the URL into the browser
  3. Copy the resulting JSON into the box at this site: https://json-csv.com/
  4. Download the file as CSV

Authentication

Some API requests require authentication by a user. In order to provide this functionality for all users, including those using Shibboleth for authentication, we provide a method to generate a "token." Users will find a button labeled "Generate New Token" at the bottom of the "My Profile" page. For API requests using the browser no further action is needed once a user has generated a token. For API requests using the command line method, copy the token for API calls requiring authentication by substituting the token for the string "token_number" in the appropriate examples.

API Requests (from the browser)

Here is the current list of commands:

For a list of institutions and plans count

https://dmptool.org/api/v1/institutions_plans_count

Successful responses to this request return an array containing zero or more instances of the institution resource along with a count of the DMPs that each institution has created


For a specific institution and plans count

https://dmptool.org/api/v1/institutions_plans_count/:id 

replace ":id" with the id of the institution (default :id = 0)

Successful responses to this request return a specific instance of an institution resource along with a count of the DMPs that this specific institution has created

Request example

https://dmptool.org/api/v1/institutions_plans_count/2


For a list of institutions and institutional administrators count

https://dmptool.org/api/v1/institutions_admins_count

Successful responses to this request return an array containing zero or more instances of the institution resource, along with a count of the users which have institutional administrator roles assigned to them


For a specific institution and institutional administrators count

https://dmptool.org/api/v1/institutions_admins_count/:id 

replace ":id" with the id of the institution (default :id = 0)

Successful responses to this request return a specific instance of an institution resource along with a count of the users which have institutional administrator roles assigned to them


For a list of institutions and contact email

https://dmptool.org/api/v1/institutions

Successful responses to this request return an array containing zero or more instances of the institution resource


For a specific institution and contact email

https://dmptool.org/api/v1/institutions/:id

replace ":id" with the id of the institution (default :id = 0)

Successful responses to this request return a specific instance of an institution resource


For a list of plans

This API request requires authentication. Note: this call will return information for all plans created by users at your institution. "Private" plans will only be displayed if created after 09-26-2016 or if you are the plan owner.

https://dmptool.org/api/v1/plans

For a specific plan

This API request requires authentication.

https://dmptool.org/api/v1/plans/:id

replace ":id" with the id of the plan


For a list of plans with all related attributes

This API request requires authentication. Note: this call will return information for all plans created by users at your institution. "Private" plans will only be displayed if created after 09-26-2016 or if you are the plan owner. Without authentication, this call returns all public plans for all institutions.

https://dmptool.org/api/v1/plans_full

For a specific plan with all related attributes

This API request requires authentication.

https://dmptool.org/api/v1/plans_full/:id

replace ":id" with the id of the plan

add .docx or .pdf to retrieve these file formats via the API

https://dmptool.org/api/v1/plans_full/:id.docx

For a list of plans owned or co-owned by a user

This API request requires authentication.

https://dmptool.org/api/v1/plans_owned

For a list of plans and all related attributes owned or co-owned by a user

This API request requires authentication.

https://dmptool.org/api/v1/plans_owned_full

For a list of users

This API request requires authentication by an Institutional Administrator or by a DMP Administrator.

https://dmptool.org/api/v1/users

For a specific user

This API request requires authentication by an Institutional Administrator or by a DMP Administrator.

https://dmptool.org/api/v1/users/:id

replace ":id" with the id of the user


For a list of templates used to create plans

This API request requires authentication.

https://dmptool.org/api/v1/plans_templates

For a list of templates created by an institution

This API request requires authentication.

https://dmptool.org/api/v1/templates_for_institution

API Requests (command line)

Here are some examples of commands with responses. All of the URLs listed in the browser requests above can be implemented using cURL commands:

For a specific institution and plans count

$ curl https://dmptool.org/api/v1/institutions_plans_count/:id 

replace ":id" with the id of the institution (default :id = 0)

Successful responses to this request return a specific instance of an institution resource along with a count of the DMPs that this specific institution has created

Request example

$ curl https://dmptool.org/api/v1/institutions_plans_count/2

Response Status: 200 OK

Headers Content-Type: application/json; charset=utf-8

Response Body

{
id: 2,
full_name: "University of Virginia",
plans_count: 289
}

For a list of plans

This API request requires authentication. Note: information is only available for plans that are set to "Public" or "Institutional" visibility for a given institution. "Private" plans will not only be displayed if you are the plan owner. Without authentication, this call returns all public plans for all institutions.

$ curl -H  "Authorization: Token token=token_number" https://dmptool.org/api/v1/plans

replace "token_number" with the token set in the "My Profile" page


For a specific plan

This API request requires authentication.

$ curl -H  "Authorization: Token token=token_number" https://dmptool.org/api/v1/plans/:id

replace ":id" with the id of the plan
replace "token_number" with the token set in the "My Profile" page