REST¶
Overview¶
REST (or REpresentational State Transfer) is an architectural style first described in Roy Fielding's Ph.D. dissertation on Architectural Styles and the Design of Network-based Software Architectures.
https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html#introduction
API Introduction¶
An API is a set of programming code that enables data transmission between one software product and another. It also contains the terms of this data exchange.
Ref: What is an API?
CRUD: CRUD stands for Create, Read, Update and Delete.
C - Create (Post) R - Read (Get) U - Update (Put) D - Delete (Delete)
Introduction about schema
https://www.altexsoft.com/blog/soap-vs-rest-vs-graphql-vs-rpc/
HTTP Methods
The primary or most-commonly-used HTTP verbs (or methods, as they are properly called) are POST, GET, PUT, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other verbs, too, but are utilized less frequently.
Below is a table summarizing the methods used by this service API.
HTTP VERB
CRUD
DESCRIPTION
POST
CREATE
Used to create new resources
NOT SAFE - NOT IDEMPOTENT
Making two identical POST will duplicate the resource
GET
READ
Retrieve a representation of a resource
SAFE - IDEMPOTENT
Multiple identical requests return the same result
PUT
UPDATE
Update or Create a resource
NOT SAFE - IDEMPOTENT
Multiple identical requests will update the same resource
DELETE
DELETE
Used to delete a resource
NOT SAFE - IDEMPOTENT §
Multiple identical requests will delete same resource
§
Calling DELETE on a resource a second time will often return a 404 (NOT FOUND) since it was already removed and therefore is no longer findable. This, by some opinions, makes DELETE operations no longer idempotent, however, the end-state of the resource is the same. Returning a 404 is acceptable and communicates accurately the status of the call.
IDEMPOTENCE
Clients can make that same call repeatedly while producing the same result.
In other words, making multiple identical requests has the same effect as making a single request. Note that while idempotent operations produce the same result on the server (no side effects), the response itself may not be the same (e.g. a resource's state may change between requests).
https://www.contrive.mobi/aviorapi/HTTPMETHODS.html
HTTP Methods¶
This has been captured at MDN HTTP Method
HTTP defines a set of request methods to indicate the desired action to be performed for a given resource. Although they can also be nouns, these request methods are sometimes referred to as HTTP verbs. Each of them implements a different semantic, but some common features are shared by a group of them: e.g. a request method can be safe, idempotent, or cacheable.
| Method | Descriptions |
|---|---|
| GET | The GET method requests a representation of the specified resource. Requests using GET should only retrieve data. |
| HEAD | The HEAD method asks for a response identical to a GET request, but without the response body. |
| POST | The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server. |
| PUT | The PUT method replaces all current representations of the target resource with the request payload. |
| DELETE | The DELETE method deletes the specified resource. |
| CONNECT | The CONNECT method establishes a tunnel to the server identified by the target resource. |
| OPTIONS | The OPTIONS method describes the communication options for the target resource. |
| TRACE | The TRACE method performs a message loop-back test along the path to the target resource. |
| PATCH | The PATCH method applies partial modifications to a resource. |
Ref: HTTP request methods
Design an API¶
| Method | Description |
|---|---|
| GET | The GET method requests a representation of the specified resource. Requests using GET should only retrieve data |
| HEAD | The HEAD method asks for a response identical to a GET request, but without the response body |
| POST | The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server |
| PUT | The PUT method replaces all current representations of the target resource with the request payload |
| DELETE | The DELETE method deletes the specified resource |
| CONNECT | The CONNECT method establishes a tunnel to the server identified by the target resource |
| OPTIONS | The OPTIONS method describes the communication options for the target resource |
| TRACE | The TRACE method performs a message loop-back test along the path to the target resource |
| PATCH | The PATCH method applies partial modifications to a resource |
Status Codes¶
Q: How do you know when to yield status code, and which codes should be returned?
A: The status code when you finish a task from requests from users, or when hit any errors.
The status code must be meaningful, because its used by another systems.
The status codes from MDN documents are useful:
HTTP response status codes indicate whether a specific HTTP request has been successfully completed. Responses are grouped in five classes:
[+] Informational responses (100 – 199)
[+] Successful responses (200 – 299)
[+] Redirection messages (300 – 399)
[+] Client error responses (400 – 499)
[+] Server error responses (500 – 599)
For more detail: HTTP response status codes
Reference¶
https://www.contrive.mobi/aviorapi/HTTPMETHODS.html
[3] API Concentps from VEEAM: VEEAM REST Methods