Introducing ADS’s OpenAPI Description and Documentation

ADS’s API, or application programming interface, is the service that accepts requests and returns the requested information. For example, when a user searches in ADS, the website sends a search request to the API, which performs the search and returns the results to the website, which formats and displays them to the user.

Early in the development of the new ADS, we decided to make its API more easily accessible and usable for our users, for development of your own tools and scripts. To that end, we’ve created documentation on API usage and examples in the form of Jupyter notebooks, provided support for users writing their own API scripts, and advertised third-party tools our users have created for our API. Users have responded by building tools to more easily search ADS within Python, maintain external bibliographies, and visualize results.

However, while our existing API documentation covered the most widely used features, such as searching ADS and using libraries, there were a number of useful features that we’ve never documented for our user base. And that doesn’t even touch all of the new features we’ve added over the last few years! Instead of updating our existing docs in a piecemeal manner, we decided to document our full API using the OpenAPI specification¹.

The OpenAPI spec is a language-agnostic, widely adopted industry standard for documenting APIs in a machine-readable way. We spent weeks documenting and describing 80+ user-facing (and, for internal use, 70+ data pipeline and internal) API operations, resulting in a comprehensive document that combines descriptions, examples, and schema for each operation. This document is now available to explore visually using our new beautiful, easy to use documentation².

New API help documentation

Our new API documentation looks a little overwhelming at first, but it’s easy to use once you get the hang of it. First, all of the available operations, or types of API requests, are organized by function in the sidebar on the left. Click on one to see the full description of that operation. To find a specific operation, you can also use the Search bar at the top, scroll through the page (all operations are listed in one long, scrollable list), or use your browser’s “find in page” function. The documentation for each operation includes the endpoint, or operation, itself (e.g. /search/query), the HTTP method to use (e.g. GET), a description of the operation, any required and optional parameters and request bodies, and the possible responses.

This is all very useful already, if similar to the existing Jupyter notebook documentation. Where these docs really shine, though, are with the built-in try-me functionality. To use this, first get your API key and copy it into the box in the Authentication section and click Set. Now you can try out the API directly from this documentation! Let’s look at an example.

API token authentication box

We’ll start with a basic search, using the operation labeled Search ADS. This operation uses the GET method and the endpoint /search/query. A longer description, with examples, is also provided in the documentation.

Search ADS operation

Scroll past the description and examples to the Request section. Here, you’ll find a list of required (marked with an asterisk) and optional parameters, each with a short helpful description. For this operation, the only required parameter is the “q” parameter; enter your search terms here. In this example, shown below, we’re searching for papers containing the word “star.” There are also some optional parameters available; here, we’re using the “fl” parameters to specify that we want the bibcode, title, author, and publication date returned for each search result.

Some other things to note about the request parameters section:

• Generally, parameters need to be URL-encoded in an API request, but when running requests via these docs, the page will automatically do the encoding for you. You can use spaces and special characters in your search terms here just as you would when searching on the ADS website, without needing to encode them.
• Below some of the parameters, there’s an example shown; click on the example to fill it in. You can also use the “fill example” button at the bottom of the list of parameters to fill all available examples.

Search ADS request parameters

Once you’ve filled in the parameters you’d like, scroll to the end of the parameter list and click Try. This will format your request, send it, and return the results. The request response is shown in the “Response” tab, in JSON format. The “responseHeader” section contains some information about the request, while the “response” section (shown below) contains the actual request results. In this example, 556,985 total results were found, and the page is displaying the first 10 in the Response box.

Search ADS response

You can scroll through the search results here, or you can click on the “curl” tab to copy the request formatted using your input parameters to use in your own scripts.

Search ADS curl command: copy this into your terminal to run the query as formatted

This works similarly for operations that have the POST HTTP request method, but there is a slight difference. Let’s look at one more example. The BibTeX export for multiple bibcodes uses the POST method. You can see that while this operation doesn’t have any parameters (though some POST operations do), it does have a request body, which is used to pass in the bibcodes you want to export. The default view for a request body is the “schema” tab, which shows the information you can pass in via the body (again, the fields marked with an asterisk are required).

BibTeX export for multiple bibcodes

To test this operation, click on the “example” tab. It defaults to an empty box; click on “fill example” to fill in the placeholder text that demonstrates the proper formatting.

Request body; click on the Example tab, then "fill example" to show the proper request body formatting

Fill in your bibcodes in the placeholder text:

Edit the placeholder request body as necessary

Then click the Try button to send the request and receive your results. The response and curl sections are similar to those for the search example above.

And that’s it! If you can follow these two examples, you’re ready to take on anything else in the documentation. You can find links to this and to the rest of our API documentation here. And we’re not done with our collection of Jupyter notebooks; we’re working on adding more notebooks with more in depth API examples. As always, email us if you have any questions.

1: This work was inspired by an ADS Hack Day project by Diab Jerius (Github).
2: This documentation is powered by RapiDoc.