# API Seller guidelines:

## Request and response body
* A route should accept and return valid JSON body
* The JSON body keys should be in `camelCase`
* The JSON enum fields should be represented in `snake_case`
* The root should be a JSON object `{}`
* The JSON date, instant, time should be represented with string in [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) format `2022-01-14T10:00:00Z`
* The nullable fields should not be serialized in case of `null` value
* The fields should adhere to [JSON standards](https://www.json.org/json-en.html) format
* The numbers should use the JSON standard `1000.25`
* The boolean should be **boolean value** `true` **NOT** string `"false"` **NOR** number `0`
## Route

### Path
* The path should be in `kebab-case`
* Use plural nouns to represent resources Ex. `/users`, `/offers`, ...
* Resource may contain sub-collection resources Ex. `/offers/{offerId}/services/{serviceId}`
* Use verbs to define an operation, like a function, it could have input and output parameters.

### Query parameters
* Query parameters should be optional
* Query parameters keys should be in `camelCase`
* Query parameters values should respect the body conventions
* Query parameters with multiple values should be encoded with value separated with comma `param=value1,value2`

### Methods

#### `GET`
* should be used to return a resource or a collection of resources
* should be **idempotent**
* could be cached with right headers
* should not have body
* use query parameters to filter, sort and limit a resource collection
* should return status code `200 OK` or `404 NOT FOUND` for not found resource

#### `POST`
* should be used to create or add to a collection a resource or for an operation
* should return status code `200 OK` or `201 CREATED` if server could return the resource, or `204 NO CONTENT` or `202 ACCEPTED` if server couldn't return resource immediately

#### `DELETE`
* should be used to delete or remove from a collection a resource
* should return `204 NO CONTENT` or `404 NOT FOUND` for not found resource

#### `PUT`
* should be used to update a **whole** resource
* should be **idempotent**
* should return status code `200 OK` or `404 NOT FOUND` for not found resource

#### `PATCH`
* should be used to update resource partially
* should return status code `200 OK` or `404 NOT FOUND` for not found resource

### Status code

#### Success 2xx
* `200 OK`: Indicates that the request has succeeded
* `201 CREATED`: Indicates that the request has succeeded and a new resource has been created as a result
* `202 ACCEPTED`: Indicates that the request has been received but not completed yet. It is typically used in log running requests and batch processing.
* `204 NO CONTENT`: The server has fulfilled the request but does not need to return a response body. The server may return the updated meta information in headers.

#### Client Error 4xx
* `400 BAD REQUEST`: The request could not be understood by the server due to incorrect syntax. The client should not repeat request without changes.
* `401 UNAUTHORIZED`: Indicates that the request requires user authentication information.
* `403 FORBIDDEN`: Unauthorized request. The client does not have access rights to the content. Unlike 401, the client’s identity is known to the server.
* `404 NOT FOUND`: The server can not find the requested resource.
* `406 NOT ACCEPTABLE`: The server doesn’t find any content that conforms to the criteria given by the user agent in the Accept header sent in the request.
* `409 CONFLICT`: The request could not be completed due to a conflict with the current state of the resource.
* `415 UNSUPPORTED MEDIA TYPE`: The media-type in Content-type of the request is not supported by the server.
* `422 UNPROCESSABLE ENTITY`: The server understands the content type and syntax of the request entity, but still server is unable to process the request for some reason.

#### Server Error 5xx
* `500 INTERNAL SERVER ERROR`: The server encountered an unexpected condition that prevented it from fulfilling the request.
* `501 NOT IMPLEMENTED`: The HTTP method is not supported by the server and cannot be handled.
* `502 BAD GATEWAY`: The server got an invalid response while working as a gateway to get the response needed to handle the request.
* `503 SERVICE UNAVAILABLE`: The server is not ready to handle the request.

## Errors
## Versioning
## Headers

Reference [RestAPI](https://restfulapi.net)