REST API Developers How-To

This page is intended as a guide for people who would like to create an api endpoint.

Bug 15165 is a good template for how to add an api endpoint to Koha.

Step 1: Find or create your Koha::Object(s) for the tables you will be using.

If Koha already has an OO class set for the table or tables you will be working with, great! Otherwise you can find the Koha::Object(s) guide here.

Step 2: Create your REST API module

Each endpoint has a Perl module that is connected to it. These modules live in Koha/REST/V1

Step 3: Create your object definition

Each table row needs a definition for the api, so it understands what it is. These definition files are written in JSON (now in YAML). The definition files live in api/v1/swagger/definitions. For example, for holds there are two definition files, one representing a single hold, and a second one representing a list of holds.

A skeleton for objects that come from the DB can be generated using the koha_schema_to_openapi.pl script from the koha-misc4dev repo. This is shipped by KohaDevBox.

Step 4: Add your object definition to the the definitions file

Add your new definition file to the list of definitions in the file api/v1/swagger/definitions.json (now api/v1/swagger/swagger.yaml under the definitions section).

Step 5: Create your path file

This file describes the various paths related to this endpoint. For example, you may have /object for listing all "objects" and /object/<id> for getting the data for the object with the id "<id>".

Step 6: Add your path file to the paths file

You will need to add your new path file to the paths file in a manner similar to how you needed to add your definition file to the definitions file. The path file is found at api/v1/swagger/paths.json (now api/v1/swagger/swagger.yaml under the paths section).

Step 7: Regenerate API spec

In order for your changes to have effect, run this command to rebundle the API spec:

perl ./build-resources.PL

In koha-testing-docker, you may need to specifically bundle the API spec like this:

yarn api:bundle

Testing API patches

After applying patches you need to run

yarn api:bundle
restart_all

Migrating Mojolicious::Plugin::Swagger2 to Mojolicious::Plugin::OpenAPI

REST API is dependent on Mojolicious::Plugin::OpenAPI, previously known as Mojolicious::Plugin::Swagger2. This migration was done in Bug 18137. Patches submitted before Bug 18137 require small updates in controller class and path definition document.

Changes in controller class (e.g. Koha/REST/V1/Patron.pm):

Start of each operation:

sub get {
    - my ($c, $args, $cb) = @_;
    + my $c = shift->openapi->valid_input or return;

Rendering each response:

    - return $c->$cb( { error => "Patron not found" }, 404 );
    + return $c->render( status => 404, openapi => { error => "Patron not found" } );
}

Changes in your path definition file (e.g. api/v1/swagger/paths/patrons.json)

{
  "/patrons": {
    "get": {
      - "x-mojo-controller": "Koha::REST::V1::Patron",
      + "x-mojo-to": "Patron#get",         # points to Koha::REST::V1::Patron::get. Do not include "Koha::REST::V1::" prefix

Rest Api HowTo

Contents