Sam Rust - explains benefits of DMPonline API
DMPonline has a REST API to enable you to query some statistics about your organisation, download your guidance, check the templates in the tool, and even create plans for your users. This blog post will detail some clients to use APIs in general, the data you can pull from our api, and run through a more detailed example. We will also talk about some of the planned extensions to the API to enable you to run your own queries on your organisation's data.
What is an API?
An API, or "Application Programming Interface", is simply a defined format for multiple systems to communicate over. It defines the language for information interchange, both that of the requests from the client, and that of the response from the server. A REST, or "Representational State Transfer", API means that the API responds to a predefined set of stateless operations.
How do I use an API?
A variety of clients can be used to communicate with an API. At a basic level, any system which can make a HTTP request can use an API. Commonly, this would be any programming language, for example Python and the requests package it uses to make web requests. For a more user-friendly approach, A GUI application like Postman can be used. For the purposes of this tutorial, we will use Postman to request data from the API, so please install that now if you want to follow-along.
Who can use the DMPonline API?
Currently, the DMPonline API usage is available to all org-admins within the tool. To check if you have permission to use the API, go to your 'edit profile' page within DMPonline by clicking your name in the top-right corner. Scrolling down, under your Institutional Credentials, if you have API access, you will see two sections `API token` and `API Information`. If you are an org-admin and do not see these sections, please get in touch and we can extend this access to your account.
What can the DMPonline API do?
The DMPonline API has a variety of endpoints, all of which are detailed in full on our wiki.
In this guide, we will focus on the statistics endpoints, but the others are listed at the above link. Currently, API users on DMPonline can pull out the number of users which have joined their organisation; the number of plans by any user based off of your organisation's non-customized templates; the number of plans created by your organisation's users grouped by template; and some generic metadata about all of the plans created by your organisation's users. Additionally, all of these endpoints can be passed a start and end date to scope the results to those created within the specified time-period. All DMPonline endpoints currently respond only in JSON, but if there is a demand for other outputs, these could be developed. If you have need for a different format, please let us know.
An example API use case
Here, we will walk through the process of querying the users-joined so far in 2019 for our organisation. In this example, we will detail the specifics for using Postman, but the steps are transferable to the application or language of your choice. Assuming you've installed Postman, create a new Request object using the orange 'New' button in the top-left.
Screenshot 1: New Request Button
To do so, we'll want to give the request a name and an optional description.
Since we are querying the users who have joined our system, I'll call the request 'Users Joined'. Here we must also choose to create a collection (essentially a folder) to keep our request grouped with like requests.
Screenshot 2: New Request Dialogue
After creating the request, we next need to add a request URL. We want to use our base URL for DMPonline, 'https://dmponline.dcc.ac.uk/', along with the URL-partial given in the api wiki page in the statistics section, for the command users_joined, '/api/v0/statistics/users_joined'.
Screenshot 3: Request URL
Now that we have told Postman the request we want to make, we next need to turn towards authentication and authorization. The wiki section on shared headers details the convention used here. We do Authorization via the 'API token' which you can find, as described above, on your 'edit profile' page. The second header, `Content-Type`, lets the API know that your want a JSON response. To put these into Postman, we will need to go to the 'Headers' tab, immediately below where we input the request URL.
These headers will be key/value pairs. The first key "Authorization" will have a value of "Token token=<API_TOKEN>", where <API_TOKEN> is the token from your edit profile page, as described above. This token is used to both authenticate us as the user, and to authorize us to view this API endpoint. The latter key, "Content-Type" should have a value of "application/json". No matter which API endpoint we use, we will want to keep these two headers the same.
If we now hit send, the above is sufficient to query the API for the number of users in your organisation, and you should get a response in JSON. Congratulations, you’ve just made your first successful API request.
Don’t get too happy just yet, because we said that for this example, we are only interested in users joining throughout 2019, so we need to scope this query to only include users created between those dates.
The API Wiki Section on Statistics details how this is done. Essentially, we are allowed to specify two additional arguments as a query string, 'start_date' and 'end_date', and specify these values as YYYY-MM-DD. In Postman, we will need to navigate to the 'Params' tab where we had previously selected 'Headers'. Here we will add a key, 'start_date', and a value, '2019-01-01'. We do not need to specify an end_date, as 2019 has not yet ended so an open-ended query is sufficient for our purpose.
Re-running the query, we now see that a smaller total number of users has joined throughout 2019 rather than over the whole year.
We have a planned extensions to the API which should be released in the near future. We are going to be creating an export of the full-text of all your organisation's plans in the system as a (large) JSON object. This should enable organisations to run their own, more interesting, analyses on their data, whether statistical, semantic analysis, or otherwise. It is also much more flexible than us defining the set of questions which you are allowed to ask about your data.
To keep up with DMPonline news, you can subscribe to the RSS feed to receive our blogs and tweets, and watch GitHub for code updates. You are also welcome to discuss our new features on the user group mailing list.