Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

REST Libraries with Ex Libris APIs

Josh Weisman on November 14th, 2017

At Ex Libris we strive to build our APIs according to accepted REST standards and practices. These include:

  • Use of HTTP verbs and status codes
  • Support for JSON and XML including WADLs, XSDs, and Content-Type headers
  • Authentication via Authorization header and API keys

Aside from providing a consistent and predictable experience for developers, use of web standards means easier integration with modern development environments. Features like "Accept" and "Authorization" headers, JSON deserialization, and HTTP error code exception handling are often provided automatically by the development platform. This allows developers to spend more time on business logic and less on plumbing.

There are many REST libraries available in various programming languages which aim to handle the low level HTTP requests. Of course, developers could write their own HTTP clients, but it's often more efficient to leave the infrastructure code to others where possible.

In order for APIs to work with these REST libraries, those APIs need to follow standard REST practices. I recently came across Refit while reading another blog. Refit is billed as an "automatic type-safe REST library for .NET Core." The Refit library handles REST plumbing such as making the HTTP Request, building the appropriate headers, parsing the response codes, and performing the necessary serialization and deserialization. Refit fits the bill as a modern REST library in a new programming environment and I wondered how the Ex Libris REST APIs would work with it.

After making sure I had the latest .NET Core and VS Code editor installed, I followed the walk through in the aforementioned blog by creating a new console app.

$ dotnet new console
$ dotnet add package refit

Then I modified the code in the sample to fit the Alma Get User API.

using Newtonsoft.Json;
using Refit;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace refitalma
{
  [Headers("Authorization: apikey <<APIKEY>>",
  "Accept: application/json")]

  public interface IAlmaApi 
  {
    [Get("/almaws/v1/users/{userName}")]
    Task<AlmaUser> GetUser(string userName);
  }

  public class AlmaUser
  {
    [JsonProperty(PropertyName = "first_name")]
    public string firstName {get; set;}

    [JsonProperty(PropertyName = "last_name")]
    public string lastName {get; set;}
  }

  class Program
  {
    public static async Task Main(string[] args)
    {
      var almaApi = RestService.For<IAlmaApi>("https://api-na.hosted.exlibrisgroup.com");
      var user = await almaApi.GetUser(args[0]);

      Console.WriteLine(
        String.Format("Successfully retrieved user: {0} ({1} {2})\n",
        args[0], user.firstName, user.lastName)
      );
    }
  }
}

This small bit of code uses the Refit library to create an Alma API request, parse and deserialize the response, and return a C# object. Here's the output when run:

$ dotnet run joshw
Successfully retrieved user: joshw (Josh Weisman)

There's a lot that could be done here, including adding support for other APIs and other methods. This might be a helpful way to build up an application based on the Alma APIs. And just as important, it shows the power of APIs that adhere to modern REST standards.