مبادئ بناء REST JSON API

تمت كتابة هذه المذكرة لتلبية الاحتياجات الداخلية (لفتح عيون الزملاء الأقل خبرة على الويب). لكن لأن لقد رأيت ما يكفي من الدراجات من الاحترام إلى حد ما ، على ما يبدو ، المكاتب ، - لقد نشرتها على المحور يبدو لي أن الكثير سيكون مفيدًا.

لماذا

آمل أن يفهم القارئ بالفعل سبب حاجته إلى REST api ، وليس نوعًا من الوحش مثل SOAP. والسؤال هو ، لماذا تتبع بعض المعايير والممارسات إذا بدا أن المتصفحات تسمح لك بالقيام بما تريد.

• المعيار HTTP هو المعيار. يعتبر عدم الامتثال لها ضارًا بالكرمة ويؤدي إلى مشاكل مستمرة في الأمان والتخزين المؤقت والمتصفحات الأخرى ، وهي ليست على الإطلاق ، ولكن ببساطة تتبع المعيار.
• {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

, ( ) .

, -, . !