HTTP API Guidelines
- Marc Johnson
This guide is intended to provide guidance of how HTTP APIs in FOLIO are intended to behave.
Collections of Records
Many of the APIs in FOLIO are intended for maintaining collections of records.
Root Path
The endpoints that make up the API for a collection of records are grouped together by a common root path e.g. /circulation/loans.
This path should include the type of records e.g. loan and some context to differentiate them from other record types with the same name e.g. /circulation/loans or /circulation-storage/loans.
This helps to reduce the potential for path conflicts in the system.
Endpoints
| Method | Sub Path | Purpose | Expectations |
|---|---|---|---|
| POST | / | Create a new record | If the new record is created, the server must respond with a 200 status code and a JSON representation of the record If the new record cannot be created, and the client can possible correct for that, then the server should respond with a 422 status code and standard validation error response (see another section, TBD) |
| GET | / | Fetch a (sub)set of records | |
| GET | /{id} | Fetch an individual record | If the record exists, the server must respond with a 200 status code and a JSON representation of the record If the record does not exist, the server must respond with a 404 status code |
| PUT | /{id} | Create or replace an individual record | |
| DELETE | /{id} | Delete an individual record |
References
The use of must, should, may etc is based upon RFC2119