Principles of building a REST JSON API

This memo was written for internal needs (open eyes to less experienced colleagues on the web). But, since I have seen enough bicycles from quite respectable, it would seem, offices, - I post it on a habr. I think many will be useful.

What for

I hope the reader already understands why he needs REST api at all, and not some kind of SOAP-like monster. The question is, why comply with some standards and practices, if browsers seem to allow you to do what you want.

• HTTP standard is standard. Its non-observance is detrimental to karma and leads to constant problems with security, caching, and other browser quirks, which are not quirks at all, but merely following the standard.
• {error: "message","result":...}
• . , api , .
• . 200 — , .

http-

METHOD URI

METHOD — (GET, PUT ..), URI — .

— key: value
, , — , .

http, ( HTTP/1.1 200 OK), , , .

.

, — UTF-8 UTF-8, .. , , "" charset.

html- , .. JSON_UNESCAPED_UNICODE . html ( - ù ), html. / \uXXXX; &#XX;. "" .

, URI , JSON. , javascript JSON.
, . json-, "" javascript, .

Accept: application/json, */*; q=0.01

API (, html URI) application/json Accept.

Accept / , , text/javascript, , "application/json".

2

Content-Type: application/json; charset=UTF-8

Content-Type: application/json; charset=UTF-8

, ,

Content-Type: multipart/form-data

,

-----------------
Content-Type: application/json; charset=UTF-8
Content-Disposition: form-data; name="data"

-----------------
Content-Type: image/jpeg
Content-Disposition: form-data; name="avatar"; filename="user.jpg"

CSRF ( ), CSRF- ( X-CSRF-Token) , . CSRF , , CSRF .

URI

, — URI

/:entity[/:id][/?:params]

, api - ,

/api/:entity[/:id][/?:params]

:

• entity — , , / . : users, dictionary
• id opt. — . , . : /users/10, /dictionary/ru/apptitle
• params opt. — (, , .). HTTP GET ( encodeURIComponent .)

URI

#^/(<entity>([a-z]\-_)+)/?(<id>([a-z][A-Z][0-9]\-_/)*)?$#

, .. , URL .

HTTP

GET /:entity/:id — getById

200 OK JSON ( - )

, id , 404 Not Found

, , .. GET HEAD . - :

Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache

GET /:entity[?param1=...¶m2=...] — get

: 200 OK JSON (.. [ ]).

, 200 OK [] .

: , — . — , , . api.

HEAD /:entity[/:id] —

GET URI, , HTTP-.

HEAD - .

pre-flight , , . , Chrome head- CORS - ( ). head- , .

(, -).

POST /:entity — :entity

JSON , .. {"field1":"value","field2":10}

201 Created ,

Location: /:entity/:new_id

.

, , id Location.

POST (RPC), 200 OK . REST RPC api — , .

, .. POST .

PUT /:entity/:id —

JSON.

204 No Data , .. .

, .. PUT - .

PATCH /:entity/:id —

, .

200 OK , getById, .

, .. PATCH .

.

DELETE /:entity/:id — , .

204 No Data , .. .

, .. DELETE 404.

OPTIONS /:entity[/:id]

, URI.

200 OK

Allow: GET, POST, ...

.

4 ( ) 5 ( ). , , text/plain ( JSON). ,

Content-Type: text/plain; charset=UTF-8

html api — , .. , .

, . . , 401 HTTP-, - react electron.

UPD . : , , (CI), . , - (.. - ) , , - - . use-case, 404 410, . 404 200 500 — .

400 Bad Request

, .

403 Forbidden

, . , . . 419

404 Not Found

, entity id .

get entity (. ).

, 418.

415 Unsupported Media Type

, . , JSON , JSON.

418 I'm a Teapot

, . , URI, .

, URI (.. ) 404, ( ). 404, 418 . — " " 410 Gone, , .. , - . 404 .

419 Authentication Timeout

, (, CSRF ). , , .

422 Unprocessable Entity

, .

, , , - .

, .

500 Internal Server Error

, .

, — console.error(err) (, ).

501 Not Implemented

, ( ) .

, -, . !