REST mythology

Materiel

Few technology in IT history has generated as much controversy as REST. The most surprising thing is that the disputing parties, as a rule, have absolutely no idea of ​​the subject of the dispute.

Let's start from the very beginning. Roy Fielding, a co-author of the HTTP and URI specifications, completed his PhD in Architectural Styles and Design of Network Software Architecture in 2000, the fifth chapter of which was titled Representational State Transfer (REST). The dissertation is available here .

As you can easily see from this chapter, it is a fairly abstract overview of a distributed network architecture that is not tied to HTTP or URLs at all. Moreover, it is not at all about API design rules; in this chapter, Fielding methodically lists the constraints faced by a distributed network software developer. Here they are:

• client and server do not know each other's internal structure (client-server architecture);
• the session is stored on the client (stateless design);
• data should be marked as cacheable or non-cacheable;
• interaction interfaces should be standardized;
• network systems are multi-layered, i.e. the server can only be a proxy to other servers;
• the client's functionality can be extended by supplying code from the server.

That's it, the definition of REST ends there. Further, Fielding concretizes some aspects of the implementation of systems in the specified constraints, but they are all completely abstract in the same way. Literally: “the key information abstraction in REST is a resource; any information that can be named can be a resource. "

The key takeaway from Fielding's definition of REST is actually this: any networking software in the world follows the principles of REST , with very, very rare exceptions.

Indeed:

• it is very difficult to imagine a system in which there would not be at least some standardized interaction interface, otherwise it will simply be impossible to develop it;
• , , , , ;
• — , , ;
• , - - ;
• , code-on-demand , , , «» , — .

, , , . , , REST . , , code-on-demand — , . S («stateless»), , , . (, , : « … , - ».)

, , 2008 , . , , :

• REST API ;
• REST API , ; ;
• REST API , .

, REST , , - REST API, API, , API.

, , , REST -2008.

REST

, ; : , ( ), . REST HTTP URL «RESTful API», .

, REST ? . , , , .

, , API - , - «» API. , 2000 , , .

«» REST- API (, )? , — .

REST , : , , ( RESTful- !).

HTTP : , , :

• URL , - ;
• , ; — , ( ), - , ;
• , ; , , ;
• , , , , .

, , — .

? ( ) . - , ; API , , , API . (, HTTP-) , , , , ; , , , -, , . HTTP-, , . - , — .

( , , . , Accept-Encoding Content-Length .)

, REST-, . stateless-: , .

. . . , :

//  
GET /me
Cookie: session_id=< >
//  
GET /delete-me
Cookie: session_id=< >
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

?

1. ; /me , ; , .
2. , .. ; .

, , , URL:

//  
GET /me?session_id=< >
//  
GET /delete-me?session_id=< >
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

, ( , ), :

1. URL , ; , , .. URL .
2. . , , , - .

REST? :

//  
GET /user/{user_id}
Authorization: Bearer <token>
//  
DELETE /user/{user_id}
Authorization: Bearer <token>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

URL , , ; , .. . DELETE-; , Authorization .

, : -, , Authorization (, , ). , , . , : , , , URL, , , GET /user/{user_id}/public-profile



— /public-profile



URL, . REST.

. , DELETE /user/{user_id}



. ?

1. HTML- , -, , , . - . , - — , - 200 — , , .

2. - HTTP-, , 504, , , , - , , . , , — , 504.

3. , , DELETE



, ; — 1 2. , ( , DELETE



), : . «» - , .

, (3) , (1) (2): . , , ; (3) (1) (2): . , , . , , ( , ) .

, ( ) : - «», , . - — , , .

, , . -, , - , .

/ / HTTP, . , -, . -, . , , , - .

, « REST API», , , :

1. « URL , » — , - . URL :

   
   
   
   
   
   
   
   • URL ;
   • , URL — , .
   
   
   

2. « HTTP- , » — . , (), (), () ; , , - — , . : , DELETE /list?element_index=3
   
   
   
   , .. , DELETE
   
   
   
   ;

   
   
   
   
   
   
   

3. « POST
   
   
   
   , GET
   
   
   
   , PUT
   
   
   
   , PATCH



DELETE
   
   
   
   » — , « » , . , , - - «» «»:

   
   
   
   
   
   
   
   • GET
     
     
     
     API , ; Cache-Control



no-cache
     
     
     
     — POST
     
     
     
     ; , - ;
   • , — PUT
     
     
     
     (, );
   • PATCH
     
     
     
     , PUT
     
     
     
     ;
   • , — , PUT /archive?entity_id
     
     
     
     .
   
   
   

4. « » — , , .

   
   
   
   
   
   
   

5. « », « URL» , REST.

   
   
   
   
   
   
   

, REST API:

1. HTTP, , .
2. URL .
3. , URL (, , query-), .
4. HTTP- API , , : , .

REST

, REST — , , API-, - — , , , , — - . , , , REST .

REST , , API-, - — , , , , — . , HTTP , REST — , — , . - .

REST — : , — . , .

REST

- REST -2008, , , HATEOAS. , , : , , , , . , , , API , , .

, , API . , ; — . API , , ( ) . , , API , , API - .

, - , API , , .

--

This is a draft for a future chapter of the book on API development. The work is done on Github . The English version of the same chapter is published on medium . I would be grateful if you could share it on reddit - I myself cannot according to the platform's policy.