intro to OBA APIs

Try it here → https://zoeken.oba.nl/api/v1/

Web-based APIs work by visiting a combination of a url and one or several final words at the end of it. The url can be defined as a base url (in our case https://zoeken.oba.nl/api/v1/), and these final words are called endpoints. Each endpoint let us make specific things.

The OBA APIs endpoints, for instance, let us get very specific in our search operations depending on the endpoint we are using, but on a basic level, they all do similar things (eg they are browsing the same catalogue and giving back results). Other APIs allow for example to edit and add more data to the server we are interacting with.

OBA’s endpoints are the following:

  • /search
  • /details
  • /refine
  • /schema
  • /index
  • /availability
  • /holdings
  • /resolver

For example, combining the base url with the /search endpoint, we have https://zoeken.oba.nl/api/v1/#/search (the /#/ it’s an inbetween element to glue together base url with endpoint).

As you can see,/search, already by the name, looks the most open-ended endpoint, allowing you to search for just a simple, generic word, a get all possible results contained in the catalogue and allowed by the API. At the same time, still by using /search, you can get very specific by way of adding more keywords to the query, and therefore obtain more refined results.

A query is the combination of one or more keywords (allowed by the API) in one string (using & to glue more keywords together).

Following a selection of endpoints with a brief explanation. The endpoints not included looks to me more specific way to get back certain informations, and or ways to check for background informations in case the main /search endpoint does not provide sufficient results. We can get into these extra endpoints after we got familiar with the “main” onese and, in particular, with the body of the catalogue itself!

General search endpoint, it looks up the whole catalogue and gets back a list of results, which can be sorted and filtered, eg by:

  • facet (restrict to specific facet, in the form of key(value))
  • pagesize (number of results)
  • s (subset, when configured)
  • lang (language)
  • sort* (the key used to sort the search results)
    • asc (ascending)
    • desc (descending)
    • def (default)
  • rctx (include previous API activity, search context / history)
  • librarian (librarian specific infos, eg marc fields and ranking infos)
  • there seems to be error with this keyword

Query example:

q=black feminism&pagesize=2

/details

This endpoint retrieves back a single record after you provided an id value for that specific item you want to check.

The id is the value returned by the API for each entry in the database.

All queries I tried did not yeld any result back. To try again.

/refine

This endpoint uses the rctx value (a keyword that keeps track of the usage and history of the API itself), and allows you to filter those informations for making new searches.

Query example:

rctx=AV3Iyw2CQBRG4f8yEEIswZhoBROQfsyAg16d98jGtTVYmmsrIbI2OZvvEMQGNdobz8dr5NBHF62ZWv@seWD2gtBYxY4EdoNR430@acuOs@0jiS2fkh5z0CmoixZdASzfcq14LxWVnxcRUPtBAXSQyfuHNBxnPsv1NXPWCZUz9AM=

I picked the rctx value from the search done using the /search endpoint. In the box with the result, look for the <rctx> tag at the beginning, and grab the long string inside it.

/index

This endpoint looks up the index list of specific sections of the API, for example:

  • author,
  • awards,
  • subjects,
  • language,
  • format,
  • targetaudience,
  • readinglevel,
  • type,
  • classification

You can get this list by adding a wrong path (eg some random characters) in the index’s endpoint box, and filling the public key and secret key.

Unclear how to use it (yet). Adding keywords other than curpage and pagesize, for example q=words gives back and error.

Errors

Whenever the query does not work as it should, the program will produce an error message. This is actually useful, as it tells you which kind of error has been made as well as it gives extra informations about what the program is expecting to receive (eg it can tell you the list of keywords it supports).

Here the list of errors coming straight from the API docs:

  • Intentional (HTTP status code 418): An intentional error code which can be used to test an API consumer’s error handling.
  • InternalError (HTTP status code 500): Signifies an unknown internal error.
  • FailedValidation (HTTP status code 409): An input parameter failed to validate.
  • NotSupported (HTTP status code 500): A particular feature is not (yet) supported by the API.
  • NotFound (HTTP status code 404): A particular requested resource was not found.
  • UnAuthorized (HTTP status code 401): Indicates the API request is not authorized.

Examples using the terminal

I’ll add in the coming days some examples of the above queries by using the terminal. Maybe it will give some better results for the endpoints not working using the embedded boxes.