Coding Guidelines - API

From Koha Wiki
Jump to navigation Jump to search

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/OpenAPI 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 

"/users": {
  "...": "..."
},
"/users/{user-id}": {
  "...": "..."
}

NOT 

"/users/{user-id}": {
  "...": "...",
  "parameters": [
    { 
      "name": "user-id",
      "required": false,
      "...": "..."
    }
  ]
}

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.

Resource names, and their attributes names can be discussed in developer meetings and the use of RFCs is encouraged.

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

SWAGGER1.3.4: mapping

API fields require a mapping from database/object field name to api field definition. The following guidelines must be followed to maintain consistency across endpoints

SWAGGER1.3.4.1 date/datetime/timestamp fields

Where a field contains a 'date' it should be consistently named *_date as opposed to date_* and it should always return a full datetime.

SWAGGER1.3.4.2 action record fields

Fields containing a record of an action should be consistently named as `action_data` and the action should be in the past tense.

Examples:

  • `created_date` - date of creation of the record
  • `modified_date` - date of last modification of the record
  • `submitted_date` - ...
  • `accepted_date` - ...
SWAGGER1.3.4.3 relation fields

Fields containing a key for a related object should be named related_id where related is the relation name from the object and if called via embed should be replaced by just the relation name.

Examples:

  • `patron_id` with `patron` returning a Koha::Patron object
  • `manager_id` with `manager` returning a Koha::Patron object
  • `creator_id` with `creator` returning a Koha::Patron object

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.2.1 POST

Successful create operations must return 201.

[DRAFT] SWAGGER3.2.1.1 POST (error, duplicate)

When a create operation fails due to duplicate object, it must return 409.

SWAGGER3.2.2 GET

Successful read operations must return 200.

SWAGGER3.2.3 PUT

Successful update operations must return 200.

SWAGGER3.2.4 DELETE

Successful delete operations must return 204.

SWAGGER3.3: Response Bodies

SWAGGER3.3.1 POST

Successful create operations should always return the created resource representation.

SWAGGER3.3.2 GET

Successful read operations should always return the resource representation.

SWAGGER3.3.3 PUT

Successful update operations should always return the updated resource representation.

SWAGGER3.3.4 DELETE

Successful delete operations should always return an empty response body.

SWAGGER3.4 Response headers

SWAGGER3.4.1 POST

Create operations should always include the Location header, pointing to the created object.

SWAGGER4: Reuse

Developer handbook

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Coding_Guidelines_-_API&oldid=30781"