1 of 12

Introduction to FOLIO APIs

FOLIO Product Council - 4 April, 2024

| www.folio.org

1

2 of 12

Definitions

Authentication Token​ (JWT)

Generated by making an API call with user credentials, the authentication token is necessary for making many API calls​

Client

Software capable of communicating to a remote system via a specified protocol (eg. Web browser, Postman, cURL)

Endpoint​

The location (URL) where clients send requests to carry out functions

Okapi​

API gateway* allowing all services to be accessed via a single entry point

Tenant​

A logically distinct collection of data in a shared resource environment with its own access controls and storage

| www.folio.org

2

3 of 12

*API Gateway

“An API gateway is a component of the app-delivery infrastructure that sits between clients and services and provides centralized handling of API communication between them. It also delivers security, policy enforcement, and monitoring and visibility across on-premises, multi-cloud, and hybrid environments.”

  • Nginx (https://www.nginx.com/learn/api-gateway/)

| www.folio.org

3

4 of 12

Things you need to use the API

  • Authentication tokens/API keys
  • Permissions
  • Endpoints
  • An API client (such as Postman)
  • API Documentation/Chrome Developer Tools

| www.folio.org

4

5 of 12

General things to know about the FOLIO API

  1. Two main types: “Okapi” and “Edge”
  2. APIs communicate in JSON*
  3. Most APIs support bulk retrieval of records with queries/filters
  4. If you can do it in the UI, you can do it via Okapi API

​

​

​

* Some Edge APIs return XML or other formats, according to the requirements of the integrating system (eg. SIP2)

| www.folio.org

5

6 of 12

Types of Okapi APIs

  • Search: Inventory-only (for now) APIs with an ElasticSearch/OpenSearch back-end optimized for indexed search
  • Storage: Fast and very flexible, but doesn’t engage business logic (mostly…)
  • Business logic: Designed to support workflow processes with a single call
  • Okapi APIs are subject to potential breaking changes with each FOLIO flower release

| www.folio.org

6

7 of 12

Edge APIs

  • Limited set of APIs intended to provide “stable” interfaces for external integrations (e.g. OAI-PMH, SIP2, orders, limited patron interaction, real time item availability)
  • Response format determined by integrating system (eg. XML, SIP2 message, etc.)
  • Two types of authentication:
    • Pre-generated API token included in the request URL (token provided by sysops/hosting)
    • Integration-specific authentication (eg. Bearer auth, SIP2 auth)

​

| www.folio.org

7

8 of 12

The Manual! https://dev.folio.org/reference/api

Raml file shows API behaviors API. View-1 and view-2 shows usage. Follow "Documentation" for specific usage​

Click on GET/POST/DELETE for specific instructions on how to read, modify, and delete records

| www.folio.org

8

9 of 12

When in doubt, how does the UI do it?

| www.folio.org

9

10 of 12

Using the FOLIO API

  • Similar to loading a web page
    • GET request tells the server you're retrieving information
    • POST tells the server you're creating something
    • PUT tells the server you're updating something
    • DELETE tells the server…�
  • FOLIO communicates using JSON (plain text) so you can use a wide variety of techniques
    • Often you can retrieve a record with GET, edit the JSON output, and then use it as input to change the record (PUT) or create a new one (POST)

| www.folio.org

10

11 of 12

FOLIO API Resources

| www.folio.org

11

12 of 12

Questions?

| www.folio.org

12