API design

While we link some tutorials on API design, some are low on details. These are some extra conventions to use.

Casing

URLs

In URLs, the most commonly used casing convention is kebab-case (lowercase with hyphens), as it improves readability and SEO:

/product-catalog
/user-profile/settings

Cast URLs to lowercase to make behaviour case insensitive.

Body data

APIs return data JSON by default. JSON stands for JavaScript Object Notation. The relation with JS and the convention there to use camelCasing makes that a good convention in our APIs.

{
  "someField": 1
}

Translations

In frontend

In case of a multilingual platform, we strive for having the bulk of translations in the frontend. Then, we don’t transport translations from back- to frontend that’d tightly couple the systems.

In communication between backend and frontend

The API best works by returning string error codes (English looking strings that most developers can understand without having to look them up) combined with HTTP status codes indicating the class of error. Frontends can then provide multilingual user friendly texts based upon those IDs.

In backend

We found only a need for having translations in the backend around email templates.

Return values and errors states

APIs that are built for a multilingual audience (e.g. a user portal) should return error codes that a frontend knows about and handles translation messages for.
If the API is also used for external developers where English can be expected as an audience, additionally, it may also contain an English string explaining the error code.
HTTP Status error codes should be used for communicating the type of failure or success, so that information doesn’t have to be added in the JSON returned.
It’s ok to specify in which field an error occurred. That helps the frontend to single out the input field that needs a correction.