Representational state transfer in short it called REST which is actually not a technology.
REST was defined by Roy Fielding in his 2000 PhD dissertation "Architectural Styles and the Design of Network-based Software Architectures" at UC Irvine - wikipedia
REST is an architectural style and not a standared. We use standards to implement it.
It is protocol agnostic and it is based on Richardson’s maturity model I will try to explain same here in short.
Level 0 (Swamp of POX) :
- This is about transport systm here it is http protocol used for remote interactions
Level 1 (Resources):
- Each resource is mapped to a URI.
Level 2 (Verbs):
- Correct http verb are used. Example: GET, POST, PUT,…
- Correct http status codes are used. Example: 404, 500…
Level 3 (Hypermedia):
- The API supports hypermedia as the engine of application state (HATEOAS)
The following are the constrainst for REST
- Client and server are seperated
- Statelessness (State is contained within the URI request & self descriptive URI’s)
- Cacheable (Each response message must explicitly state if it can be cached or not)
- Layered System (Client cannot tell what layer it connected to)
- Uniform interface (API and consumers share one single technical interface)
I will share some samples on how REST request and response should be
HTTP Method | Request Payload | Sample URI | Response Payload |
---|---|---|---|
GET | – | api/authors | author[] / author collection |
GET | – | api/authors/{authorId} | author/single author |
POST (Insert operation) | author/single author | api/authors | author / single author |
PUT (Update operation) | author/single author | api/authors/{authorId} | single author / empty |
PATCH (Partial update) | JSON patch document on author | api/authors/{authorId} | – |
DELETE | – | api/authors/{authorId} | – |
HEAD (To check if resource exist) | – | api/authors
api/authors/{authorId} |
– |
OPTIONS (describs communication options) | – | api/authors | – |
Apart from these Status code play a major role because http status code can tell consumer of API wheather or not the request worked out as expected. Here are some important HTTP status code
Status Code | Description |
---|---|
200 | Success/OK |
201 | Created |
204 | No Comment |
300 | Redirection |
400 | Bad request |
401 | Unauthorised |
403 | Forbidden |
404 | Not Found |
405 | Method not allowed |
406 | Not acceptable |
409 | Conflict (example resource already exist) |
415 | Unsupported media type |
422 | Unprocessible entity (Validation mistake) |
500 | Internal Server error |
This can be categorised like if response code is in 400’s it means isssue is from the consumer side. Also if response code is 500’s it is due to Server