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