As Isaac noted back in the March 2022 ticket of the month, we are regularly asked about how to get some basic information out of our API, for reporting, for research, for general curiosity.
As you can see from those examples, you can construct API queries directly in our swagger documentation, or use them right in your browser with the help of a JSON formatter extension.
That’s great if you just want to take a quick glance at something. We do that all the time to quickly check things like:
- When was the last time a specific organization registered a new DOI?
- What proportion of our total registered items have abstracts?
- How many different types of Creative Commons licenses are included in the metadata?
- Can I find a random example of a journal article with a related preprint?
- Etc.
But for more in-depth or ongoing API use, it can be a little awkward to construct query URLs in a browser. They can be difficult to keep track of, save for later, or make slight adjustments to, and the resulting JSON metadata records can be difficult to parse through in detail. One possible solution to this is to use an API client like Postman.
Just for the sake of transparency, Crossref doesn’t have any kind of formal relationship with Postman. So, this is not an official endorsement of their product. That said, we (meaning Crossref’s support team) do use it fairly regularly, and find it to be helpful. It’s also free to use, and very fully-featured; and, it’s designed to occupy that middle ground between “uh, what’s an API?!” and “it’s cool, I’ll just write my own script.”
One especially helpful thing about Postman is that Claire Froelich, who works for Postman’s Student Program, has created a collection in Postman called Crossref Unified Resource API.
A collection is a group of preformatted saved queries. You’ll need to create a Postman account, or login with an existing account, to access it, but once you do, you can search for that collection and ‘fork’ it into your own workspace.
A fork is just a copy of that collection that you can customize for your own use, without impacting the original. To fork, click on the three dots to the right of the collection name in your Collections panel, then select “Create a fork” from the menu. You’ll be prompted to give your fork a name and a location. The default options are almost always fine.
Once you’ve created your fork of the collection, you can open it up in your workspace by selecting the arrow to the left of the collection name.
If you select the collection as a whole, you’ll see the API documentation displayed in the center panel. Then you can drill down into the folders on the left-hand panel to select among the preformatted queries. Each folder corresponds to a different route or endpoint, with example queries nested beneath.
In this example, we’ll look at the prefixes route. But, a great thing about using a collection like this is that you can edit any query as needed to experiment with different parameters or search terms.
One way to do this is to duplicate an existing query. I’m going to duplicate the /prefixes/:prefix/works query. Just click on the three dots to the right and select Duplicate.
Then rename your new query by selecting Rename in that same manner. In this case I’m going to name it “all works for a prefix”.
If you look at the existing parameters which were duplicated from the original query, you’ll see a number of them that are active:
- sample, which tells the API to give you back a random sample of between 1 and 100 items that meet the specified criteria
- mailto, which identifies you to the API, and then routes your queries to a dedicated Polite server pool which tends to have slightly better response time and stability.
- query, which indicates a search term
- filter, which can limit results along a number of lines. in this case, it’s filtering by publication date
There is also a path variable, which in this case indicates the DOI prefix we’re looking for information about. In other routes, the path variable may be a member ID, funder ID, ISSN, DOI, etc.
If you look at the mailto value in the query parameters and both the base URL and mailto value in the GET request URL at the top of the center panel, you’ll see they’re populated with placeholders in curly brackets. This means they’re variables set at the collection level.
This is another very useful feature of collections. You can set a variable value once for the whole collection, and then you don’t have to repeatedly add it to each query. To see the collection-level variables use the Variables tab in the main collection view.
You will need to change that “youremail@email.com” email variable value to your own email address. This is important so that Crossref can contact you in the unlikely event that your rate or type of queries are accidentally causing problems for our servers. But, because mailto is set as a collection-level variable, you only have to make that change once.
If you don’t want to use your email address, just toggle off the mailto parameter for all the queries you send. This will cause your requests to be routed to our Public, rather than Polite, server pool.
Back to our example query, to run a basic request for all content from a given prefix, we’re going to need to toggle off the sample, query, and filter parameters, and then add the prefix we’re looking for in the prefix path variable.
Based on a recent user’s request to access metadata pertaining to particular organization, AIAA, I’m going to use their prefix which is 10.2514. So, altogether, the new parameters look like this:
Then, just click “Try” or “Send” to get the results.
At the top of the results pane, you’ll see the response status (200, ideally), the time it took to get the response, and the size of the response data. Beneath that, you’ll see the response itself. It’s the same thing you would get if you entered that request - https://0-api-crossref-org.library.alliant.edu/prefixes/10.2514/works - into a browser. But Postman gives you the options to save the query, save the results, change the data type (when supported by the API), and get a code snippet in a number of different languages which will allow you to embed that same API request into your code.
You can further refine your query by adding filters or facets in the parameters as key:value pairs. For example, if you toggle the filter parameter back on, you can replace “from-pub-date:2015-02,until-pub-date:2015-02” with any filter supported in our documentation. For example, if you only wanted results that pertained to conference materials, you can filter to return just conference proceedings and conference papers by adding the filter value “type:proceedings-article,type:proceedings”. When you add that filter and resend the request, you can see the total results changed from 296,116 to 195,043, and you know that all the subsequent records are for conference proceedings/papers.
To take another example, let’s say you wanted to see a list of all the known organizations that funded research resulting in publications on that same 10.2514 prefix. Toggle off the filter that you had previously used, and toggle on the facet and rows parameters. For the facet value use “funder-name:*” and for the rows value use “0”. That will return a facet list of 2500+ funder names and the number of AIAA’s registered items associated with each funder, but no metadata records for any of that prefixes DOIs.
If you’re interested in using Postman to get metadata from Crossref, I’d encourage you to experiment with requests from various routes in the collection and try different parameters to see how that changes the results. And, if you get stuck, you can always refer back to the API documentation at api.crossref.org or in the Overview section of the collection in Postman.
For a much more thorough introduction to APIs in general, and to using the Crossref API Postman collection in particular, this webinar recording is an excellent resource: API 101 for publishers, researchers, and librarians with Postman and Crossref - ConTech.Live