gabesoft / kapi

Rest API server (spec)

Entities

Users

Feeds

Posts

UserPosts

UserFeeds

Queries

Tags

Meta attributes (shared by all entities)

_type : the type of resource

_id : a unique identifier for a resource

_href : the URL of the current resource

_links : an array of relationship URLs

• each link is an object containing rel and href fields

{
  "rel": "user",
  "href": "http://example.com/api/users/a123"
}

Supported content types

• Content-Type: application/json; charset=utf-8

Response status codes

• http://www.restapitutorial.com/httpstatuscodes.html

Success

Status Code	Status	Used With	Notes
200	OK	PUT,PATCH
201	Created	POST
202	Accepted	Async requests
204	No Content	DELETE
204	No Content	OPTIONS
304	Not Modified	GET	with ETag header

Failure

• all error codes should be accompanied by an error payload that explains the error

{
  "message": "error reason",
  "documentationUrl": "http://api/documentation"
}

Status Code	Status	Description
400	Bad Request	the request was invalid or cannot be served
401	Unauthorized
403	Forbidden	the server understood the request but is refusing it
404	Not Found
405	Method Not Allowed	the requested URL exists but the HTTP method is not applicable
406	Not Acceptable	the request has accept headers incompatible with what the server is able to generate
409	Conflict	signals a duplicate entries attempt
422	Unprocessable Entity	the server cannot process the entity, entity is invalid
415	Unsupported Media Type	the accepted media type is not supported

Per HTTP method

Method	Action	Collection (/users)	Resource (/users/3)
POST	Create	201	405, 409
GET	Read	200	200, 404 (invalid id)
PUT	Replace	405	200, 204, 404
PATCH	Modify	405	200, 204, 404
DELETE	Delete	405	200, 204, 404

Headers

Header		Returned On
Allow	GET,PUT,…	405 response
Location	resource-url	creation
Link	pagination	collection query
X-Total-Count	total count during pagination	collection query

Examples

• Link: https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5; rel=”next”, https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3; rel=”last”, https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5; rel=”first”, https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5; rel=”prev”
• Link: http://(…)/elements/generated-id1, http://(…)/elements/generated-id2

Query and filtering

Via query string parameters

• GET /users?name=joe&createdAt=123
• GET /users?where=(name eq “joe”) and (createdAt lt “123”)
• GET /users?where=profile.phone eq “112-332-4423”

Filtering operators

Operator	Description	Example
eq	equal	name eq ‘Tom’
ne	not equal	name ne “Tom”
gt	greater than	height gt 6
ge	greater than or equal	version ge “1.0”
lt	less than
le	less than or equal
in	in list	id in [1,2,3]
not in	not in list	id not in [1,2,3]
contains	contains	name contains “the”
is null	is null	version is null
is not null	is not null	description is not null
and	combine two conditions via AND	(active eq true) and (version ge “1.1”)
or	combine two conditions via OR	(active eq false) or (version ge “1.1”)

Supported types

Type	Sample Query
Integer	price gt 123
Float	price lt 2.5
String	name eq “Tom”	surrounded by double quotes
Date (UTC)	startDate gt 2017-01-05T05:27:03.213Z	ISO 8601
Boolean	admin eq true

Via query object for custom queries

• objects that support queries should be query-able via a query id like so ?q=<query-id>

Fields

• all fields used in query, filtering, sorting, can target nested entities (e.g. user.profile)

Sorting

• sort is allowed over multiple fields, -desc, +asc (default) by using the sort query parameter
• GET /users?sort=-createdAt,+name,+profile.address

Partial response

• by default the server returns a full entity with all the nested entities
• a subset of fields can be requested when necessary by using the include query parameter
• one or more fields can be excluded using the exclude query parameter
• only an include or an exclude parameter is allowed
• a request containing both an include and an exclude parameter will result in a 400 error
• GET /users?include=createdAt,name,id,profile.address,profile.phone
• GET /posts?exclude=description

Pagination

• all collection endpoints will accept start and limit parameters
• GET /users?start=3&limit=10

Validation

• http://json-schema.org/
• http://stackoverflow.com/questions/23853626/best-practice-for-validating-json-requests-with-yesod

Endpoints

Definition

Method	Scope	Example	Semantics
GET	collection	/users	retrieve all resources in a collection
GET	resource	/users/3	retrieve a single resource
HEAD	collection	/users	retrieve all resources in a collection (header only)
HEAD	resource	/users/3	retrieve a single resource (header only)
POST	collection	/users	create one or more resources in a collection
PUT	collection	/users	replace one or more resource (missing fields are deleted)
PUT	resource	/users/3	replace a resource (missing fields are deleted)
PATCH	collection	/users	update one or more resource (missing fields are left untouched)
PATCH	resource	/users/3	update a resource (missing fields are left untouched)
DELETE	resources	/users/3	delete a resource
OPTIONS	any	/	return available HTTP methods and other options

Supported verbs per endpoint

• there should be an apps:id/.. for every resource except apps

Endpoint	GET	POST	PUT	PATCH	DELETE	HEAD	OPTIONS	Bulk Supported
apps	1	1	0	0	0	1	1	0
apps:id	1	0	1	1	1	1	1	0
users	1	1	0	0	0	1	1	0
users:id	1	0	1	1	1	1	1	0
apps:id/users/	1	1	0	0	0	1	1	0
apps:id/users/:id	1	0	1	1	1	1	1	0
feeds	1	1	1	1	0	1	1	1
feeds:id	1	0	1	1	1	1	1	0
posts	1	1	1	1	0	1	1	1
posts:id	1	0	1	1	1	1	1	0
user-posts	1	1	1	1	1	1	1	1
user-posts:id	1	0	1	1	1	1	1	0
user-feeds	1	1	1	1	1	1	1	1
user-feeds:id	1	0	1	1	1	1	1	0
users:id/user-feeds	1	1	1	1	1	1	1	1
users:id/user-feeds/:id	1	0	1	1	1	1	1	0
apps:id/users/:id/user-feeds	1	1	1	1	1	1	1	1
apps:id/users/:id/user-feeds/:id	1	0	1	1	1	1	1	0
queries	1	1	0	0	0	1	1	1
queries:id	1	0	1	1	1	1	1	0
apps:id/queries/	1	1	0	0	0	1	1	1
apps:id/queries/:id	1	0	1	1	1	1	1	0
tags	1	1	1	1	1	1	1	1
tags:id	1	0	1	1	1	1	1	0
apps:id/tags/	1	1	1	1	1	1	1	1
apps:id/tags/:id	1	0	1	1	1	1	1	0
users:id/tags	1	1	1	1	1	1	1	1
users:id/tags/:id	1	0	1	1	1	1	1	0
users:id/queries	1	1	1	1	1	1	1	1
users:id/queries/:id	1	0	1	1	1	1	1	0
apps:id/users/:id/tags	1	1	1	1	1	1	1	1
apps:id/users/:id/tags/:id	1	0	1	1	1	1	1	0
apps:id/users/:id/queries	1	1	1	1	1	1	1	1
apps:id/users/:id/queries/:id	1	0	1	1	1	1	1	0

Inputs and outputs

• all methods not in the table below will receive a 405 status code with Allow headers

Method	Url	Query	Headers	Body	–>	Status	Headers	Body
GET	users:id		Accept: *			200/404		User:JSON
			Accept: application/json			200/404
			Accept: other			406
			ETag/If-None-Match			200/304
GET	/users	include/exclude	Accept: *			200/400	Link	[User]:JSON
		where	Accept: application/json			200/404	X-Total-Count
		sort	Accept: other			406
		start
		limit
DELETE	users:id					204/404
POST	/users			User:JSON		201/409	Location
POST (bulk)	/users			[User]:JSON		200	Link
PUT	users:id			User:JSON		204
PUT (bulk)	/users					200
PATCH	users:id					204
PATCH (bulk)	/users					200
HEAD	ANY					200	ETag
							Last-Modified
OPTIONS	ANY					200	Allow

Notes

Bulk operations

• Bulk operations are performed by sending an array of objects at the collection level
• Some collection resources accept both a single element and a collection for methods such as PUT,POST,PATCH and according to the input payload the server will detect if a single or bulk operation is requested
• Bulk operations never fail but will return an array of responses (including error and success results)
• Bulk creations will return a list of Link headers instead of the Location header
• Bulk creations will return a 200 status instead of 201 since not all requested items may succeed in being created but the operation as a whole will always succeed

Idempotency

• All GET, PUT, DELETE, HEAD, and OPTIONS requests for single operations are idempotent

Store specific

Elastic-search

• elastic search documents will be indexed when modified

Resources

http://restcookbook.com

http://restful-api-design.readthedocs.io/en/latest

http://restlet.com/blog/2015/05/18/implementing-bulk-updates-within-restful-services

http://amundsen.com/media-types/collection/format/

http://www.restapitutorial.com/lessons/restquicktips.html

http://www.restapitutorial.com/lessons/httpmethods.html

https://www.targetprocess.com/guide/integrations/rest-api/rest-api-response-paging-sorting-filters-partial-get/

Diagrams

https://raw.githubusercontent.com/wiki/Webmachine/webmachine/images/http-headers-status-v3.png

https://camo.githubusercontent.com/4e15cccf2a9277dcca2c8824092547dee7058744/68747470733a2f2f7261776769746875622e636f6d2f666f722d4745542f687474702d6465636973696f6e2d6469616772616d2f6d61737465722f6874747064642e706e67

Rest API server (implementation)