Learning more about Thoth’s GraphQL API

An application programming interface (API) provides users the means for one program to access the information and capabilities of another; put more simply, it is how programs can communicate with each other.1 Thoth, the open metadata dissemination system developed in COPIM, has an open-source GraphQL API, meaning, any user can construct and manipulate queries—using a pre-defined code language that requests information—to retrieve existing data from Thoth’s database. This is dissimilar from most databases, which restrict what users can query to a particular set of options. Incorporating an open API such as GraphQL prioritizes users, allowing them the agency to retrieve the data they seek, not the server. Ultimately, the benefit of Thoth’s GraphQL is that it empowers its steadily increasing number of users — currently, more than a dozen publishers, among them Open Book Publishers, punctum books, Mattering Press, African Minds, mediastudies.press, and Edinburgh Diamond are already using Thoth for their metadata needs.

On August 19, 2022, Thoth met with its users to demo GraphQL in a workshop. Led by Thoth’s software engineer Javier Arias, the team of COPIM’s Work Package 5 guided users through its GraphQL API and demonstrated how to query the API, write queries, and export the resulting data into a spreadsheet. A recording of the session can be found on Thoth’s User Manual and on Youtube here:

As many users realized during the workshop, learning the API won’t necessarily happen overnight—especially for first-time learners—and it takes time to adjust to the particularities of the query format.2 For anyone interested in refining their ability to use GraphQL with Thoth, Javi has provided some examples below of common queries that can be used as exercises to familiarize users with the API. These queries include searching for a publisher and their publisher ID and finding a particular book. 

For example, if you want to search for information relating to a particular publisher, you will need its publisherId. The following query will return a list of all publishers’ names and IDs, so you can find the name of the publisher you are interested in, and then note its corresponding ID:

You can then use the publisherId to query books by that publisher:

Meanwhile, if you want to search for information relating to a particular book, and you have its workId, you can use the work query. You can include its relations to obtain nested details of related works (chapters in this case):

A query for a complete work record, with its most important attributes, would look like this:

We are grateful to everyone who participated in Thoth’s GraphQL API workshop. We hope that all users feel confident to use Thoth’s GraphQL for their data needs. We look forward to future workshops and collaborations with Thoth users and the larger OA community. Happy querying!

Header image: photo by Marvin Meyer on Unsplash.