Skip to content

Latest commit

 

History

History
181 lines (123 loc) · 5.43 KB

rest-api.md

File metadata and controls

181 lines (123 loc) · 5.43 KB

REST API Design

Table of Contents

Concepts

  • REST = REpresentational State Transfer

  • Safe API

Six Constraints

  • Uniform interface
  • Client–server
  • Stateless
  • Cache-able
  • Layered system
  • Code on demand (optional)

Interfaces of Rest API

Input

  • Resource must be noun, no verbs in URI

Non REST

  • GET https://api.control.nexplore.com/core/ + getEntity/:id
  • HTTP Verb: (no use)
  • URI: (directory) + action + resource + identifier

REST (1)

  • GET https://api.control.nexplore.com/core/ + entities/:id
  • HTTP Verb: action
  • URI: (directory) + resource + identifier

REST (2)

  • GET https://api.control.nexplore.com/core/ + entities
  • HTTP Verb: action
  • URI: (directory) + resource (collection)

HTTP Verbs

  • ONLY use the followings

  • Create: Post

  • Retrieve: Get

  • Remove: Delete

  • Replace: Put

  • Partial Update: Patch

Output

Status Code

  • Create: 201
  • Retrieve: 200
  • Remove: 204
  • Replace: 200
  • Partial Update: 200
  • (Async task): 202
  • (User Errors): 4XX
  • (System Errors): 5XX

Examples

  • Retrieve one: GET /entities/:id
  • Retrieve all: GET /entities
  • Create: POST /entities
  • Update/Replace: PATCH or PUT /entities/:id
  • Remove: DELETE /entities/:id

Discussion (1)

All actions with side effect target one resource at one call. WHY???

Is it possible to handle multiple different resources / same resource with different types at one call?

  • mPOST?
  • mGET?
  • mPUT?

If supporting multiple resources in a single call, think about -

  • How to manage transaction when more than one resources?
  • How to manage failures? rollback / atomic / best effort

Standard & Framework

Richardson Maturity Model

  • Level 0 - None
  • Level 1 - Resources
  • Level 2 - HTTP Verbs
  • Level 3 - Hypermedia Controls

JSON::API

  • A complete specification on how to implement REST API Level 3

Discussion (2)

Singular resource vs Plural resource(s)?

  • De facto standard: plural (but opinionated)

How to configure different shape of the output?

  • use of query as the additional parameters

How to add some additional checking?

  • put those information to header?

Issues on REST

If working for multiple resources

  • how to make it transactional?

Hard to describe some endpoints accurately through REST

  • too little operations allowed (verbs)

e.g.

  • upload
  • send
  • deliver

Very hard to describe non-data status change

  • lock / unlock / approved?

Filter collection data can be very very hard

  • Query parameter is hard to specify data with types (string based)

e.g.

  • null vs 'null' vs undefined vs '' (empty string)

-> Graphql

Reference