Coding Guidelines - API

From Koha Wiki

Jump to: navigation, search
Home
Koha > Technical > Development

Contents

Basics

These rules are supplemental to the general Coding Guidelines, they are not an alternative.

A guide for creating a new api endpoint can be found here.

RESTful API

Swagger2 is a RESTful API Specification Language; It allows us to describe our RESTful API in such a way that others may benefit from automated API consumer code generation in their applications. Care should be taken to 'design' your API routes as thoroughly as possible to enable others to use it reliably.

Koha code wise, we have opted to base our new API on the modern Perl web framework Mojolicious and use the Mojolicious Plugin for Swagger2 to take advantage of 'Specification first programming'.

SWAGGER1: Resources (Swagger Paths)

SWAGGER1.1: Distinct routes

Distinct paths should be used for distinct operations, don't be tempted to re-use a path. For example:

USE

<span class="st0">"/users"</span><span class="sy0">:</span> <span class="br0">{</span> <span class="st0">"..."</span><span class="sy0">:</span> <span class="st0">"..."</span> <span class="br0">}</span><span class="sy0">,</span> <span class="st0">"/users/{user-id}"</span><span class="sy0">:</span> <span class="br0">{</span> <span class="st0">"..."</span><span class="sy0">:</span> <span class="st0">"..."</span> <span class="br0">}</span>

NOT

<span class="st0">"/users/{user-id}"</span><span class="sy0">:</span> <span class="br0">{</span> <span class="st0">"..."</span><span class="sy0">:</span> <span class="st0">"..."</span><span class="sy0">,</span> <span class="st0">"parameters"</span><span class="sy0">:</span> <span class="br0">[</span> <span class="br0">{</span> <span class="st0">"name"</span><span class="sy0">:</span> <span class="st0">"user-id"</span><span class="sy0">,</span> <span class="st0">"required"</span><span class="sy0">:</span> <span class="kw2">false</span><span class="sy0">,</span> <span class="st0">"..."</span><span class="sy0">:</span> <span class="st0">"..."</span> <span class="br0">}</span> <span class="br0">]</span> <span class="br0">}</span>

SWAGGER1.2: Resource names

As far as possible an api route should be 'guessable' for the uninitiated api consumer. Thus, routes that are not discipline specific should attempt to use generic widely recognised terms.

Example:

USE

/users

NOT

/borrowers
OR
/patrons
OR
/members

In this case, 'borrowers'/'patrons' and 'members' are very Koha specific. Along with that they do not actually distinguish between staff and public users. The generic and widely recognised 'users' term is more appropriate here (and this is likely highlighting a bad coding decision from koha's history ;) )

NOTE: It is also recommended to use plural form for route names, and singular form/verbs for actions suffixes

SWAGGER1.3: Resource description

All resources should be defined in full in their own definition file.

SWAGGER1.3.1: type

All fields of a resource should have a type associated with them

SWAGGER1.3.2: required

All resources should have a list of required fields specified

SWAGGER1.3.3: description

Although not strictly required, a brief description of what the field should contain is very useful for the api consumer

SWAGGER2: HTTP Methods

We are following RESTful best practice which means using HTTP methods to denote stateful actions.. this roughly equates to:

  • POST - Create
  • GET - Read
  • PUT - Update
  • DELETE - Delete

With the addition of PATCH for partial update.

Sometimes 'actions' do not align nicely to the main object. For these cases the recommendation is to map an action resource atop the main resource; for example POST /users/{id}/block to block a user and DELETE /users/{id}/block to remove it.

SWAGGER3: Requests and Responses

SWAGGER3.1: Request Parameters

All request parameters should be specified in the swagger specification file

SWAGGER3.2: Response Codes

All achievable response codes should be specified in the swagger specification file

SWAGGER3.3: Response Bodies

Updates & create operations should always return the updated/created resource representation

SWAGGER4: Reuse

Personal tools