REST stands for **Re**presentational **S**tate **T**ransfer protocol. Roy Fielding defined REST in his [Phd dissertation](https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf) in the year 2000.
- Use the prefix **V#** to indicate the version of your URL like `api/v1/people` or `api/V2/people`.
- Never use a dot notion as prefix like `api/v1.2/people` to indiate your version. By doing that it will confuse the developer using the API. When there is frequent updates or depreciation of API versions.
- #### Limiting PUT and POST requests
- Due to similarity of PUT to POST operation, which could be easily exploited to create a new record.
- Use POST requests to **create** records, whereas PUT request to be **updating** of existing records.
- Create a checker function to check for PUT request that is used to **create** new records.
- Resources can have `one-to-one`, `one-to-many`, and `many-to-many` relationships etc. Mapping them correctly is crucial.
- **One-to-One** Mapping
For example, `Countries/1/capital` suggests a one-to-one relationship between a country and a capital city. This means a country can only have one capital. This type of relationship means that one row relates only to one row in another table (one country, one capital in two different tables). This type of relationship is not common and is often used to break up the amount of data in one row of a table.
- **One-to-Many** Mapping
For example, `Tickets/145/messages/4` suggests one-to-many relationship between `tickets` and `messages`. Meaning `1` ticket has `N` messages. Message isn't standalone resource. You can't have `/messages/4`.
- **Many to Many** Mapping
For example, `/usergroups/345/users/56` suggests select 345th user group and get user with id 56. However, one user might be in multiple `usergroups` i.e. `/usergroups/209/users/56` is also valid. In such case so for seperating the dependant resource `users` into a seperate endpoint like `/users/56` and provide resource linking in `/usergroups/209/users/56`
- #### **API Parameters**
- **PATH** : *required* to access the resource E.g. `/cars`, `/fruits`
- **Query Parameters** : *optional* filter the list E.g. `/cars?type=SUV&year=2010`
- **Body** : Resource specific logic. Advance search query. Sometimes it might have both Query and body.
- **Header** : Should contain global or platform wide data. E.g. API key parameters, encrypted keys for auth, device type information e.g. mobile or desktop or endpoint, device data type e.g. xml or json. Use header to communicate these parameters
- #### HTTP Status Codes
Use correct status codes
| Codes | Meaning |
| ------------- |:-------------:|
| 1xx | Request received and understood. |
| 2xx | Action requested by client was received, understood and requested. |
| 3xx | Client must take additional action to complete the request. Most of these status codes are used in URL Redirection. |
| 4xx | Intended for situations where it seems the error was caused by the client. |
- Returns no content. But can also return `200 OK` if API intends to send the deleted resource for further processing.
The useful **3xx**!
- **304 - Not Modified**
- Useful status code to tell you that the browser saw no change in delta from the file it just received and the one it had cached, so it used the cached version instead.
REST APIs not only support `xml`, but also support `html`, `json` and `csv`, among other formats. [Wikipedia](https://en.wikipedia.org/wiki/Representational_state_transfer)
