REST API Principles

Resources

• Every core domain concept is its own resource: /api/v{version}/{entities}/{id}. Resource names are plural kebab-case, e.g. /api/v1/flow-categories/{id}.
• When the domain language treats a multi-word concept as a single word, write it as one word. Document such exceptions to the naming rule explicitly in the project applying it.

Versioning

• The v{version} segment is the major version only: v1, never v1.2.
• It is required for public APIs, where we do not control all clients; optional for internal APIs, where all clients can easily be moved along with API changes.

Methods and status codes

• GET is safe; PUT and DELETE are idempotent; POST creates or executes.
• 400 Bad Request for validation failures; 409 Conflict for requests that conflict with the resource's current state.

Collections