Originally posted by **PBharose** March 10, 2023
# URL Design and Semantics
We prefer a RESTful approach in the URL design, which has the benefit of making the URLs self-documenting and understandable to developers.
JSON is the preferred format of the response, although different protocols such as BSON, ProtoBuf, and Avro can be considered for specific contexts.
## URL Structure
### RESTful URLs are structured based on the following pattern:
```bash
https://myapi.azurewebsites.net/api/{domain}/{version}/{resource}?parameter={parameter}
https://myapi.azurewebsites.net/api/{domain}/{version}/{resource}/{id}?parameter={parameter}
```
The domain parameter is optional but recommended, and it's used to categorize a set of endpoints that operate in the same bounded context.
The version fragment must be present in the URL structure, even though we usually create APIs that are 1:1 with the client, and we rarely have to keep online multiple versions of the API.
The resource fragment should meet the following guidelines:
- It should be identified by a noun, rather than a verb
- If the API handles a collection of the resource, it should be plural
- It should be serialized in camelCase format.
Examples of good URLs:
```bash
https://myapi.azurewebsites.net/api/v1/invoices
https://myapi.azurewebsites.net/api/calendars/v1/surveys/22/executions
```
Examples of wrong URLs:
```bash
https://myapi.azurewebsites.net/api/v1/invoices/123/pay
```
(It contains a verb, it should be payment)
```bash
https://myapi.azurewebsites.net/api/invoices/123/pay
```
(It doesn't contain the API version)
### HTTP Verbs
Manipulations of resources happen through HTTP Verbs: GET, POST, PUT, PATCH, and DELETE.
PUT vs PATCH: both update the entity.
- PUT expects the whole entity as input and uses it to update the whole entity.
- PATCH should only update the fields explicitly passed in the request.
Discussed in https://github.com/PBharose/NodeJS-Assignment/discussions/3