Rest Api HowTo

= 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
=See also=
* Coding Guidelines - API
Category:Guidelines