Prinzipien zum Erstellen einer REST-JSON-API

Dieses Memo wurde für interne Bedürfnisse geschrieben (um die Augen weniger erfahrener Kollegen im Web zu öffnen). Aber weil Ich habe genug Fahrräder von ziemlich angesehenen Büros gesehen, wie es scheint, - ich habe es auf der Nabe verteilt Es scheint mir, dass viele nützlich sein werden.

Warum

Ich hoffe, dass der Leser bereits versteht, warum er die REST-API wirklich braucht, und nicht irgendeine Art von Monster wie SOAP. Die Frage ist, warum Sie einige Standards und Praktiken befolgen, wenn Sie mit Browsern das tun können, was Sie wollen.

• Der HTTP-Standard ist der Standard. Die Nichteinhaltung ist schädlich für das Karma und führt zu ständigen Problemen mit der Sicherheit, dem Caching und anderen Browser-Quacksalbern, die überhaupt keine Macken sind, sondern einfach dem Standard folgen.
• {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

, ( ) .

, -, . !