Guest post: COUNTER API (sushi) validation

In this guest post, Beda Kosata from our partner Big Dig Data, the developers of the COUNTER harvesting tool Celus, explains how to validate a response from a COUNTER API (sushi) server for COUNTER Release 5.1 using the OpenAPI specification. While this check is not as comprehensive as the Validation Tool, it will validate the overall structure of your COUNTER API response – and as your developers will tell you, having the correct response structure is necessary for COUNTER compliance.

Read on to learn how to build a simple Python script using an existing OpenAPI library together with the COUNTER API OpenAPI spec to validate the responses from a COUNTER API server…

A brief introduction to OpenAPI

OpenAPI is a language-agnostic specification for describing REST APIs. It is a standard way to describe the whole API, including the endpoints, request and response formats, HTTP status codes, etc. Thus the OpenAPI spec is not suitable for validating files, but rather should be used to validate responses from the API.

The OpenAPI spec is usually written in YAML or JSON format and there are many tools that can help create, edit, and validate the spec.

COUNTER API OpenAPI spec for Release 5.1

You can find the OpenAPI spec for the COUNTER API (sushi) here:

https://countermetrics.stoplight.io/docs/counter-sushi-api/.

COUNTER started using stoplight.io as part of Release 5.1 to host the COUNTER API (sushi) details. It provides a nice interface for browsing the OpenAPI spec, and it’s a good way to learn more about the COUNTER API. For the purpose of this blog, we want to export the spec in JSON format. To do that,

• Click on the “Export” button in the top right corner of the page
• Choose the “Original” option
• Save the file to your disk.

The file should be named COUNTER_SUSHI_API.json and I will refer to it as such in the rest of the post.

The Python environment

The Python script will use the OpenAPI spec to validate the responses from a COUNTER API server. To make it versatile we will pass the OpenAPI spec file and the URL of the server as command line arguments, so it could be used to validate any server against any OpenAPI spec.

The script was tested using Python 3.10 on a Linux system, but any recent version of Python 3 should work. The description should be pretty OS agnostic, so it should work on Windows and MacOS as well. You may have to replace the straight slashes with backslashes in file paths on Windows.

I would recommend using a virtual environment for running the script, so you can install the necessary libraries without affecting your system Python installation. To create a virtual environment, run:

python -m venv venv
source venv/bin/activate

Then you can install the necessary libraries inside the virtual environment.

The bulk of the work will be done by the openapi-core (https://github.com/python-openapi/openapi-core/) library, which is a Python
OpenAPI library. The library is available on PyPI, so you can install it using pip:

pip install openapi-core

To make HTTP requests, we will use the requests (https://docs.python-requests.org/en/master/) library. It should be already installed as a dependency of the openapi-core library. If not, you can install it using pip:

pip install requests

The Python script itself

You can find the full script validate.py in this Gist: https://gist.github.com/beda42/a228f28916d8fb210a96201c688450d8. Download it and place it in the same directory as the OpenAPI spec file COUNTER_SUSHI_API.json.

You can then run it from the command line like this:

python validate.py "https://sashimi.celus.net/r51/reports/tr?customer_id=foo&begin_date=2024-06-01&end_date=2024-06-30&requestor_id=bar&api_key=baz"

In the above example, we are using a fake COUNTER API server called Sashimi (https://github.com/Big-Dig-Data/sashimi) so as not to overload any real sushi servers and not to expose any real data. You should replace the URL with the URL of your COUNTER API server.

Note: Don’t forget to put the whole URL in quotes, so that it is passed correctly to the script – otherwise the ampersands will be interpreted by the shell and the script will not work correctly.

The spec file COUNTER_SUSHI_API.json will be used by default, but you can specify a different file by using the -s argument:

python validate.py -s /tmp/whatever-api.json https://whatever.url/

The result

If everything goes well, you should see this message:

Validation successful

If there are any errors, you will see a message like this:

Validation failed. Errors:

followed by a list of errors that the script encountered while validating the response. Details of the errors will be automatically included, so that you can see what went wrong.