Skip to main content

An API wrapper over the FOLIO LSP API Suite (Formerly OKAPI).

Project description

FolioClient

example workflow
FOLIO Client is a simple python (3) wrapper over the FOLIO LMS system API:s

Features

  • Convenient FOLIO login and OKAPI Token creation
  • Wrappers for various REST operations
  • Most common reference data for inventory are retrieved as cached properties.
  • Fetches the latest released schemas for instances, holdings and items. Very useful for JSON Schema based validation.

Installing

pip install folioclient

Basic Usage

Create a new FolioClient instance

import os
from folioclient import FolioClient

fc = FolioClient(
    "https://folio-snapshot-okapi.dev.folio.org", 
    "diku", 
    "diku_admin", 
    os.environ.get("FOLIO_PASSWORD")
) # Best Practice: use an environment variable to store your passwords

Query an endpoint in FOLIO

# Basic query, limit=100
instances = fc.folio_get("/instance-storage/instances", key="instances", query_params={"limit": 100})

# mod-search query for all instances without holdings records, expand all sub-objects
instance_search = fc.folio_get(
    "/search/instances",
    key="instances", 
    query='cql.allRecords=1 not holdingsId=""', 
    query_params={
        "expandAll": True,
        "limit": 100
    }
)

NOTE: mod-search has a hard limit of 100, with a maximum offset of 900 (will only return the first 1000)

Get all records matching a query without retrieving all records at once

# Get all instances. When performing this operation, you should sort results by id to avoid random reordering of results
get_all_instances = fc.folio_get_all(
    "/instance-storage/instances", 
    key="instances", 
    limit=1000, 
    query="cql.allRecords=1 sortBy id"
)

"""
Now you can iterate over get_all_instances, and FolioClient will retrieve them in batches of 1000, 
yielding each record until all records matching the query are retrieved.
"""
for instance in get_all_instances:
    ...

Convenience methods for basic FOLIO HTTP Actions (GET, PUT, POST)

FolioClient objects provide convenience methods for standard GET, PUT, POST and DELETE HTTP requests. In addition to the folio_get examples above:

# Put an existing object, return is based on the endpoint, often an empty 204 response
instance = instances[0]
put_object = fc.folio_put(f"/instance-storage/instances/{instance['id']}", payload=instance)

# Post a new object, 
user = {}
post_user = fc.folio_post("/users", payload=user)

Auth Token management

Once you have instantiated a FolioClient object, it will manage the lifecycle of your auth token, retrieving a new valid token as needed. If you need to access the auth token directly:

# The token is accessible as a property of the FolioClient instance
auth_token = fc.okapi_token
print(auth_token)
eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJNQXJBbm10WUV2azV6TTdtQ3puMmIzZDJlZ1NsNk5rZUsxRjBaV1cxd1d3In0.eyJleHAiOjE3NDU1MDk3NzUsImlhdCI6MTc0NTUwOTE3NSwianRpIjoiOTIyMGEyODktMzRlZS00ODcwLWIwMGQtMTQ5N2UyNzNlYmYyIiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay1zZWJmLmludC5hd3MuZm9saW8ub3JnL3JlYWxtcy9mczA5MDAwMDAwIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImNoYW5pIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiZnMwOTAwMDAwMC1hcHBsaWNhdGlvbiIsInNpZCI6Ijg2MzhkZGYzLWQ0YmMtNDA0Ny04YjQzLTdmYjU4N2FjZjk5NCIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiLyoiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbImRlZmF1bHQtcm9sZXMtZnMwOTAwMDAwMCIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCIyNWUxOWFkMDhjMmVkMDhiYzAwNjk1NzMwMWUzOGNhYzMwNTU3MDk5Il19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJ1c2VyX2lkIjoiNzM0NmQ3NmMtMTQyYi00MjhlLThhZWQtMTQ2Mzg4NmM5ZmMxIiwibmFtZSI6IkNoYW5pIEF0cmVpZGVzIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiY2hhbmkiLCJnaXZlbl9uYW1lIjoiQ2hhbmkiLCJmYW1pbHlfbmFtZSI6IkF0cmVpZGVzIiwiZW1haWwiOiJicm9va3N0cmF2aXNAbWlzc291cmlzdGF0ZS5lZHUifQ.nWSz8W88uDr3qq5Qlmh4M3z8VuPXHCB1y3gJiFtEPfLY8haTvELAqOkQUqodhhXiNbyRcN0ywxbsFsidAlCuSpaBEdZItxFaJMxg00du3Cpqd7QkHTHXt8pvqMtYq7rTbYRe98S_nVSVtHczP2OzJ5Tf5ONW_sbleu2xPG11Cv6asibhIToVF2zGWEQYMBPl-m91BQdx7s8aNqKYpiL5G-zuhD4SkstEA1Zbp4n-pSAeTb7XcWCA__lYllKVMPFLEt_C1lt46u8nS3i5eixx2ANblCDK_RHcOEuHisiTett8kKoQL8CeqDT4DzNTr8EzC-XBV9jOnCc6el59_nzVOw

FOLIO request headers

If you would rather roll your own http requests, you can use FolioClient simply to manage your auth session with FOLIO. You can access the FOLIO headers object containing the current valid auth token via the okapi_headers property of the FolioClient object:

import requests
with requests.Session() as client:
    response = client.get(fc.gateway_url + "/instance-storage/instances", headers=fc.okapi_headers)
    response.raise_for_status()
    print(response.json())

Switching tenants in a consortial (ECS) environment

When working with an ECS environment, you can authenticate as a user with multiple tenant affiliations and switch affiliations simply by assigning the desired tenant's tenant ID value to the okapi_headers['x-okapi-tenant'] key:

fc.okapi_headers['x-okapi-tenant']
'cs01'

# Assign member tenant ID
fc.okapi_headers['x-okapi-tenant'] = "cs01m0001"

# Reset the headers back to original tenant
del fc.okapi_headers
fc.okapi_headers['x-okapi-tenant']
'cs01'

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

folioclient-0.70.2.tar.gz (17.7 kB view details)

Uploaded Source

Built Distribution

folioclient-0.70.2-py3-none-any.whl (16.8 kB view details)

Uploaded Python 3

File details

Details for the file folioclient-0.70.2.tar.gz.

File metadata

  • Download URL: folioclient-0.70.2.tar.gz
  • Upload date:
  • Size: 17.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for folioclient-0.70.2.tar.gz
Algorithm Hash digest
SHA256 f28987efabad8974c7a5f55fa81aa3bd61f694c0e86fb9b1ca09046f97f7e8bd
MD5 7f09e52cbaf86842f2f58bade1ad46bb
BLAKE2b-256 a797e1b570844b68ab7c9b90572191ae1cdae2856b741f1d143106f08da94da5

See more details on using hashes here.

Provenance

The following attestation bundles were made for folioclient-0.70.2.tar.gz:

Publisher: python-publish.yml on FOLIO-FSE/FolioClient

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file folioclient-0.70.2-py3-none-any.whl.

File metadata

  • Download URL: folioclient-0.70.2-py3-none-any.whl
  • Upload date:
  • Size: 16.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for folioclient-0.70.2-py3-none-any.whl
Algorithm Hash digest
SHA256 c98560639c56c1755ff35acae64cb4299455bcccfc4b770cd036acfb6c7e6586
MD5 935aeafad1e4c398d0b46ce3b3384550
BLAKE2b-256 d3c2fd065fba69c373235e313ba22188f1aaf6c8365d2c1962048038835b7987

See more details on using hashes here.

Provenance

The following attestation bundles were made for folioclient-0.70.2-py3-none-any.whl:

Publisher: python-publish.yml on FOLIO-FSE/FolioClient

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page