The Dash Data Publication service is now allowing access to dataset metadata and public files through a read-only API. This API focuses on allowing metadata access through a RESTful API. Documentation is available at https://dash.ucop.edu/api/docs/index.html.
There are a number of ways to test out and access this API such as through programming language libraries or with the Linux curl command. This short tutorial gives examples of accessing the API using Postman software which is an easy GUI way to test out and browse an API and is available for the major desktop operating systems. If you’d like to follow along please download Postman from https://www.getpostman.com/ .
We are looking to receive feedback on the first of our Dash APIs, before we embark on building our submission API. Please get in touch with us with feedback or if you would be interested in setting up an API integration with the Dash service.
Create a Dash Collection in Postman
After you’ve installed Postman we want to open Postman and create a Dash collection to hold the queries against the API.
- Open Postman.
- Click New > Collection.
3. Enter the collection name and click Create.
Set Up Your First Request
1. Click the folder icon for the collection you just set up.
2. Click Add requests under this collection.
3. Fill in a name for your request, select to put it in the Dash collection you created earlier and click Save to Dash to create.
4. Click on the request you just created in the left bar and then click the headers tab.
5. Enter the following key and value in the header list. Key: Content-Type and Value: application/json. This header ensures that you’ll receive JSON data.
6. Enter the request URL in the box toward the top of the page. Leave the request type on “GET.” Enter https://dash.ucop.edu/api for the URL and click Save.
Try Your Request
1. Test out your request by clicking the Send button.
2. If everything is set up correctly you’ll see results like these.
Information about the API is being returned in JavaScript Object Notation (JSON) and includes a few features to become familiar with.
– A links section in the JSON exposes Hypertext Application Language (HAL) links that can guide you to other parts of the API, much like links in a web page allow you to browse other parts of a site.
– The self link refers to the current request.
– Other links can allow you to get further information to create other requests in the API.
– The curies section leads to some basic documentation that may be used by some software.
Following Links and Viewing Dataset Information
Postman has a nice feature that allows you to follow links in an API to create additional requests.
- Try it out by clicking the url path associated with stash:datasets which shows as /api/datasets.
2. You’ll see a new tab open for your new request toward the top of the screen and then you can submit or save the new request.
3. If you send this request you will see a lot of information about datasets in Dash.
Some things to point out about this request:
– The top-level links section contains paging links because this request returns a list of datasets. Not all datasets are returned at once, but if you needed to see more you could go to the next page.
– The list contains a count of items in the current page and a total for all items.
– When you look at the embedded datasets you’ll see additional links for each individual dataset, which you could also follow.
– You can view metadata for the most recent, successfully submitted version of each dataset that shows as dataset information here.
Hopefully this gives a general idea of how the API can be used and now you can create additional requests to browse the Dash API.
Hints for Navigating the Dash Data Model
– As you browse through the different links in the Dash API, it keep the following in mind.
– A dataset may have multiple versions. If it has only been edited or submitted once in the UI it will still have one version.
– The metadata shown at the dataset level is based on the latest published version and the dataset indicates the version number it is using to derive this metadata.
– Each version has descriptive metadata and files associated with it.
– To download files, look for the stash:download links. There are downloads for a dataset, a version and for an individual file. These links are standard HTTP downloads that could be downloaded using a web browser or other HTTP client.
– If you know the DOI of the dataset you wish to view, use a GET request for /api/datasets/<doi>.
– The DOI would be in a format such as doi:10.5072/FKK2K64GZ22 and needs to be URL encoded when included in the URL.
– See for example https://www.w3schools.com/tags/ref_urlencode.asp or https://www.urlencoder.org/ or use the URL encoding methods available in most programming languages.
– For datasets that are currently private for peer review, downloads will not become available until the privacy period has passed.
