Tech Blog

OpenAPI Support in Alma APIs

Ex Libris has started rolling out support for the OpenAPI standard. The standard is owned by the OpenAPI Initiative and is defined as a “specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services” (Wikipedia). By providing the specification for our APIs in OpenAPI format, you can now integrate with tools and libraries that support the standard.

OpenAPI

There are many primers on OpenAPI on the web, so we’ll suffice with a high level overview here. Using OpenAPI, all of the parts of a REST API can be defined, including:

  • Endpoints (paths)
    "paths": {
      "/almaws/v1/users": {
      ...
  • Methods (i.e. get, post, put)
    "get": {
      "description": "This API returns a list of Users, sorted by last name.",
      "summary": "Retrieve users",
      ...
  • Parameters
    "parameters": [
      {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
        "default": "10",
        "type": "integer"
      },
      "description": "Limits the number of results. Optional. Valid values are 0-100. Default value: 10."
    },
    ...
  • Request bodies, including accepted content types and the payload object schema
    "requestBody": {
      "description": "This method takes a User object. See [here](/alma/apis/docs/xsd/rest_user.xsd?tags=POST)",
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "./schemas/rest_user-post.json#/rest_user-post"
          }
        },
    ...
  • Responses, including response codes, available content types (i.e. application/json, application/xml) and the response object schema
    "responses": {
      "400": {
        "description": "Bad Request..."
      },
      "200": {
        "description": "OK - This method returns an object based on rest_users.xsd. See [here](/alma/apis/docs/xsd/rest_users.xsd)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "./schemas/rest_users.json#/rest_users"
            }
          },
    ...
  • Security (basic, API key, token, etc.)
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "description": "API key used to authorize requests. Learn about how to create API keys at [Alma REST APIs](https://developers.exlibrisgroup.com/alma/apis/#defining)",
        "in": "query",
        "name": "apikey"
      }

     

OpenAPI can be expressed in either JSON or YAML format. YAML is a serialization standard which is meant to be more human-friendly. It can be directly transformed from JSON. For example, the beginning of the OpenAPI standard can be expressed in JSON as follows:

{
  "openapi": "3.0.1",
  "info": {
    "version": "1.0",
    "title": "Ex Libris APIs"
}

And as YAML as follows:

openapi: "3.0.1"
 info: 
   version: "1.0"
   title: "Ex Libris APIs"

Tools

There is widespread and growing support today for the OpenAPI specification in many toolchains.

Swagger

Swagger is a set of tools built around the OpenAPI specification, maintained by a company called SmartBear.

Tip: OpenAPI used to be called “Swagger”. The names were forked to create a separation between the community-supported spec and the toolset created and sponsored by a company (Smartbear)

The most popular Swagger tools include:

  • Swagger UI: Generates an API “console” from an OpenAPI spec
  • Swagger Editor: Tool for creating and validating an OpenAPI spec
  • Swagger Codegen: Tool for creating server stubs and client SDKs based on an OpenAPI spec

Here’s how the OpenAPI spec for the Alma Configuration API looks in the Swagger Editor:

And the same specification in the Swagger UI:

 

Other Tools

OpenAPI has wide industry support and continues to gain traction. A small sample of such support includes:

Getting Started

You can start exploring the OpenAPI specifications for Alma REST APIs with any of the tools mentioned in this post. Each API area (for example, Users) includes a new OpenAPI section at the bottom with links to the specification documents in both JSON and YAML. It also includes a link to the Swagger Editor which is a great way to dive in and learn about the sections of the specification.

Keep an eye out for additional blog posts in the future on OpenAPI.

 

Leave a Reply