Koha API Research

Comprehensive analysis of Koha ILS API capabilities for mobile integration

Introduction

This document outlines the research findings on Koha Integrated Library System (ILS) API capabilities, focusing on features relevant to student users. The research aims to identify the appropriate API endpoints and authentication mechanisms for integration with the mobile application.

Authentication Mechanisms

Koha REST API supports multiple authentication mechanisms to secure API access:

HTTP Basic Authentication

The simplest form of authentication, where credentials are sent with each request:

  • Username and password are sent in the Authorization header
  • Must be used over HTTPS to ensure security
  • Enabled via the RESTBasicAuth system preference

OAuth2 Authentication

Token-based authentication that provides enhanced security:

  • Supports client credentials grant flow
  • Access tokens have configurable expiration
  • Enabled via the RESTOAuth2ClientCredentials system preference
  • Recommended for mobile applications

Cookie-based Authentication

Session-based authentication using cookies:

  • Uses the same session as the OPAC
  • Useful for integrations within the same domain
  • Not recommended for mobile applications due to cross-domain limitations

API Endpoints Structure

The Koha API is organized into two main categories:

Staff Endpoints

Endpoints for administrative functions, typically requiring staff credentials:

  • Located at the root of the API path
  • Provide full CRUD operations on library resources
  • Require appropriate permissions

Public Endpoints

Endpoints designed for library patrons and public access:

  • Located under the /public path
  • Provide read-only access to most resources
  • Allow limited write operations for user-specific actions (holds, renewals)
  • Most relevant for the mobile application

Student-Relevant API Endpoints

The following endpoints are most relevant for student users and will be utilized in the mobile application:

Catalog Search and Browsing

GET /api/v1/public/biblios

Search and retrieve bibliographic records from the catalog.

Query Parameters:

  • q - Search query (title, author, subject, etc.)
  • limit - Maximum number of results to return
  • offset - Starting position for results
  • sort_by - Field to sort results by
  • order - Sort order (asc or desc)

GET /api/v1/public/biblios/{biblionumber}

Retrieve detailed information about a specific bibliographic record.

Path Parameters:

  • biblionumber - Unique identifier for the bibliographic record

Checkouts and Borrowing History

GET /api/v1/public/patrons/{patron_id}/checkouts

Retrieve current checkouts for a patron.

Path Parameters:

  • patron_id - Unique identifier for the patron

GET /api/v1/public/patrons/{patron_id}/checkouts/history

Retrieve borrowing history for a patron.

Path Parameters:

  • patron_id - Unique identifier for the patron

Query Parameters:

  • limit - Maximum number of results to return
  • offset - Starting position for results

Renewals

POST /api/v1/public/checkouts/{checkout_id}/renewal

Renew a checked out item.

Path Parameters:

  • checkout_id - Unique identifier for the checkout

Holds

GET /api/v1/public/patrons/{patron_id}/holds

Retrieve current holds for a patron.

Path Parameters:

  • patron_id - Unique identifier for the patron

POST /api/v1/public/biblios/{biblionumber}/holds

Place a hold on a bibliographic item.

Path Parameters:

  • biblionumber - Unique identifier for the bibliographic record

Request Body:

{
  "patron_id": "123",
  "pickup_library_id": "MAIN",
  "expiration_date": "2025-06-30",
  "notes": "Optional notes"
}

DELETE /api/v1/public/holds/{hold_id}

Cancel a hold.

Path Parameters:

  • hold_id - Unique identifier for the hold

Bookings

GET /api/v1/public/bookings

Retrieve bookings for resources.

Query Parameters:

  • patron_id - Filter by patron ID
  • from_date - Start date for booking period
  • to_date - End date for booking period

POST /api/v1/public/bookings

Create a new booking for a resource.

Request Body:

{
  "patron_id": "123",
  "resource_id": "456",
  "start_date": "2025-05-15T10:00:00",
  "end_date": "2025-05-15T12:00:00"
}

Patron Information

GET /api/v1/public/patrons/{patron_id}

Retrieve patron information.

Path Parameters:

  • patron_id - Unique identifier for the patron

PUT /api/v1/public/patrons/{patron_id}

Update patron information.

Path Parameters:

  • patron_id - Unique identifier for the patron

Request Body:

{
  "email": "student@university.edu",
  "phone": "555-123-4567",
  "address": "123 Campus Drive"
}

Integration Considerations

Authentication Strategy

For the mobile application, we recommend implementing OAuth2 authentication:

  • More secure than Basic Authentication for mobile clients
  • Tokens can be securely stored on the device
  • Automatic token refresh can be implemented
  • Allows for fine-grained permission control

Caching Strategy

To optimize performance and support offline functionality:

  • Cache catalog search results for offline browsing
  • Store user's checkout history locally
  • Implement time-based cache invalidation
  • Use ETags for efficient cache validation

Error Handling

Robust error handling is essential for a good user experience:

  • Implement appropriate error messages for different API response codes
  • Handle network connectivity issues gracefully
  • Provide retry mechanisms for failed operations
  • Queue operations when offline for later synchronization

Rate Limiting

To prevent API abuse and ensure fair usage:

  • Implement client-side throttling for API requests
  • Batch related requests when possible
  • Handle 429 (Too Many Requests) responses with exponential backoff
  • Monitor API usage patterns to optimize requests

Conclusion

The Koha ILS provides a comprehensive REST API that can be leveraged to build a feature-rich mobile application for students. By focusing on the public endpoints and implementing proper authentication, caching, and error handling strategies, we can create a seamless mobile experience that integrates well with the existing Koha system.

The identified API endpoints cover all the essential functionality required for the mobile application, including catalog search, checkout management, renewals, holds, bookings, and patron information. These endpoints will form the foundation of our backend integration with Koha.