API

Architecture
Formatting
Errors

Architecture

The team generally follows RESTful and JSON API. In addition, before designing a new API, review the recommended practices outlined in the Heroku API Design Guide.
Use version endpoints e.g. v1/, v2/.
Endpoints and parameters must be documented. Postman and OpenAPI (Swagger) are the preferred tools.

Formatting

Use String format for Float/Double attributes.
```
{
  "amount": 123.456789
}
```
```
{
  "amount": "123.456789"
}
```
Different protocols, software, and hardware may support different numeric precisions in serialization and deserialization. This difference might cause unintended rounding errors.
Use the RFC 3339 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ) for DateTime attributes.
```
{
  "updated_at": "2023-07-13 12:02:33"
}
```
```
{
  "updated_at": "2023-07-13T12:02:33.123Z"
}
```
RFC 3339 is listed as a profile of ISO 8601, see the diff at RFC 3339 vs ISO 8601.

The Z part stands for the Timezone offset; it has two normal representations. A version expressed in UTC (‘Zulu’) time, with a time zone offset of 00:00 (e.g. 2023-01-01T02:07:14.456Z), and a version expressed in local time (e.g. 2023-12-31T21:07:14.345+07:00).

Errors

The conventional HTTP status codes must be used to indicate the success or failure of an API request. In general:

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error that failed given the information provided (e.g., required parameters missing, invalid pin or OTP, invalid token, etc.).
Codes in the 5xx range indicate an error with the servers.

Regardless of the HTTP status code, add an error_code that references the occurring error to make the error payload more explicit for consumers. For example, some 4xx errors that could be handled programmatically for different reasons (e.g., expired token or invalid login credentials) with the same HTTP status code.

These error codes from error objects shall be well documented so that the team consuming the API (i.e. mobile or front-end) can properly handle the errors in their client apps.

Check out more about the JSON:API error objects for reference