REST JSON APIの構築の原則

このリーフレットは、内部のニーズ（Webで経験の少ない同僚の目を開くため）のために作成されました。 しかし、なぜなら 私はかなり評判の良い自転車を十分に見ました、それはオフィスのようです-私はそれをハブに広げました 多くの人が役に立つように思えます。

なぜ

SOAPのような怪物ではなく、REST APIが本当に必要な理由を読者が既に理解していることを願っています。 問題は、ブラウザがあなたが望むことをすることを許可しているように見える場合、なぜいくつかの標準と慣行に従うかです。

• 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=...&param2=...]



— 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

, ( ) .

---

, -, . !