# REST

## REST API#

• Representation State Transfer
• An architectural pattern for creating an API that uses HTTP as its communication method
• for designing network based application
• Resource:
• If we have endpoint/URI(URL or URN), lets say https://127.0.0.1/coders then we have resource. Here coders is a resource.
• Its nothing new, we already used to make URLs that way
• Representation:
• When a client makes a GET request to coders/toran/ client gets following JSON response  1 2 3 4 { "nickname": "toran", "powerLevel": 5 }
• so, this is representation in the form of JSON having metadata
• representation also could be XML, HTML
• the same applies when a client sends a request which contains a 'coder' data, its sends representation
• Representational State:
• like browsing the web
• a HTML page is a representation of a resource at current state (or current data) of that resource.
• When we submit a form, we just send a representation back to the server
• Representational State Transfer
• a client and server exchange representations of a resource, which reflects its current state or desired state.
• So, REST is a way for two machines to transfer the state of a resource via representations.

Note: There is a very common confusion in terminology. "Resource" - In URI "app/questions/1" here "1" is also know as resource and at the same time "questions" is also know as resource. - Some people around the globe also use "1" as record/entity & "questions" as resource. - We could generalize "1" as "resource object" and "questions" as "resource class"

## HTTP Request Methods (HTTP verbs)#

HTTP defines a set of request methods to indicate the desired action to be performed for a given resource

### GET#

 1 2 GET /questions/:question_id HTTP/1.1 Host: www.example.com
• The GET method requests a representation of a specified resource.
• GET request should only used for data retrieval. (But can also be used for submit/posting/sending data)
• a resource is mentioned in URL.

### POST#

 1 2 POST /questions/ HTTP/1.1 Host: www.example.com/
• Used to modify/update an existing entity of a specified resource.
• Do mention the object/entity of the resource in the URL to update
• we should use PUT and PATCH for update
• PUT would create a new unwanted resource when the resouce doesn't exists while updating that particular resource
• PATCH is perfect for partial updation
• But there is no restrictions using POST for updates
 1 2 POST /questions/ HTTP/1.1 Host: www.example.com
• Used to submit a new entity/data to a specified resource.
• Do not mention the object/entity of the resource in the URL while creating it. Otherwise it will give "Resource Not Found" error.
• Use this if you want server to let the name, the URL object while creating a new one
• Causes change in state of the resource
• Two simultaneous POST requests works fine (lets say, 1st request is updating some part & 2nd request is updating other part of an object)
• The UPDATE performed by the POST method might not result in a resource that can be identified by a URI.

### PUT#

• Used to create a new resource entity or overrite (Completely replaces) the existing one.
• For a new resource entity:  1 2 PUT /questions/:new_question_id HTTP/1.1 Host: www.example.com
• To overrite an existing one:  1 2 PUT /questions/:existing_question_id HTTP/1.1 Host: www.example.com
• Usefull when you know the name of the entity/object
• Use this if you want to name the URL object while creating a new one
• PUT is idempotent, so if you PUT the same object twice, it has no effect (will overrite)
• Can create or update an object with the same URL

### DELETE#

 1 2 DELETE /api/resource/:id HTTP/1.1 Host: www.example.com/
• Deletes/destroyes a specified resource object/entity/record

### PATCH#

 1 2 3 4 5 6 7 PATCH /users/1 HTTP/1.1 Host: www.example.com Content-Type: application/example If-Match: "c0b42b66e" Content-Length: 120 {changes}

where [changes] could be JSON/XML like {email:'[email protected]'}

• Used to make partial modification to an existing resource object/entity.
• Works differently than POST & PUT for update
• Need to have URL object known
 1 2 3 4 5 6 7 $curl http://0.0.0.0:8010/ --head HTTP/1.0 200 OK Server: SimpleHTTP/0.6 Python/3.7.3 Date: Sat, 23 Aug 2020 17:14:52 GMT Content-type: application/json; charset=utf-8 Content-Length: 13306 • Ask for the response same as GET but without response/message body. • i.e. returns Header & Status Code, except Body • Usages? • to fetch headers, or to verify the API by status code • to get the content size of a media file - without fetcching it actually • request has body? No • can send query params only • successful response has body? No • safe? Yes • idempotent? Yes • cacheable? Yes • allowed in HTML forms? No ### OPTIONS#  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20$ curl /api/resource -X OPTIONS -i # responds with header; and empty body HTTP/2 200 OK date: Sat, 07 Aug 2021 16:48:46 GMT content-length: 0 vary: Origin access-control-allow-origin: https://api.toran.com access-control-allow-credentials: true access-control-allow-headers: Accept,Accept-Version,Content-Length,Content-MD5,Content-Type,Date,X-Auth-Token,x-requested-with,x-csrftoken,x-page-total,Accept-Language,Connection,x-page-limit,Accept-Encoding,x-page-page,cache-control access-control-allow-methods: GET,HEAD,POST,PATCH,PUT,DELETE access-control-max-age: 3600 content-security-policy: default-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; strict-transport-security: max-age=31536000; includeSubDomains; preload referrer-policy: strict-origin-when-cross-origin permissions-policy: geolocation=() server: kong/2.1.4 # (optional) Body, btw DRF sends body by default {"name":"Api Resource","description":"","renders":["application/json","text/html"],"parses":["application/json","application/x-www-form-urlencoded","multipart/form-data"]}
• Used to describe the communication option for the target resource
• tell the capabilities of the API server, like list of supported:
• HTTP methods by the server
• Content-Type
• Accepts
• request has body? No
• can send query params only
• successful response has body? Yes (optional)
• safe? Yes
• idempotent? Yes
• cacheable? No
• allowed in HTML forms? No
• usage?
• to communicate with server during CORS case (preflight)
• tell the server that I will do this, do you support those?

 1 2 3 4 OPTIONS /resources/post-here/ HTTP/1.1 Host: bar.example Access-Control-Request-Method: POST Access-Control-Request-Headers: X-PINGOTHER, Content-Type
meaning, I'll do POST and with headers X-PINGOTHER and Content-Type. do you supposet those?

Response:

 1 2 3 HTTP/1.1 204 No Content Access-Control-Allow-Methods: POST, GET, OPTIONS Access-Control-Allow-Headers: X-PINGOTHER, Content-Type

### CONNECT#

• starts two-way communications with the requested resource
• it can be used to open a tunnel
• ref
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/connect
• https://reqbin.com/Article/HttpConnect

### TRACE#

• Performs message loop-back test along the path to the target resource

## HTTP Response Codes#

• 1XX informational
• 101 switching protocol
• 2XX Success
• 200 (Ok)
• 201 (Created)
• 204 (No Content)
• 3XX Redirection
• 304
• 4XX Client Error
• 404
• 5XX Server Error
• 501 (Not Implemented)