Tech Blog

API tips for beginners

So, you have decided to use the Alma APIs. This is great!
Alma API documentation contains 3 important areas that we strongly recommend you read:

This article includes some tips and best practice that will help you to implement Alma APIs smoothly and safely.

1. Verify the environment

Alma has a special API: Retrieve General Configuration. This API returns the institution code (in institution field), the Alma URL (in alma_url field) and an indication whether the API key is configured to work with production or with sandbox environment (in environment field).
After generating an API key, we recommend to run this API and ensure that the API key is configured correctly, with the correct environment.
In order to run this API, the application should be defined to include Configuration  API, with read permission.

2. Verify write permission

For POST or PUT API, we recommend to run the test API and make sure that the API key is configured with write permission.
There are several test APIs, in the various API areas:

For example: POST /almaws/v1/bibs/test.

If write permission is configured, the following response should be retrieved:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<test>POST - OK</test>

If this is not the response – check your application configuration.  It is probably not configured with write permission.

3. Submit the API as a standalone

Before writing your code which calls Alma’s APIs, we suggest running the APIs from a standalone client to make sure it works as expected.
You can submit GET APIs directly in a browser: just paste the API request directly in the browser’s address bar and press Enter.
Helpful tip: To view JSON in your Chrome browser, check out the JSON Formatter third party plugin.
In order to submit POST and PUT APIs, you need a REST client. There are several free REST clients, for example the Chrome advanced REST client or Postman.

4. GET before PUT

Alma PUT APIs are working in a “swap-all” mode: Calling applications are expected to run a GET before PUT, and send the entire entity with the relevant fields modified. Missing elements will be given default values.

Leave a Reply