API Guidelines

This document outlines our API design standards and conventions. We'll use the /sites collection for illustrative purposes.

This document details the API design standards and conventions our team must adhere to. The guiding principle here is simplicity, consistency, and leveraging HTTP methods for their semantic meaning.

Conventions and Payloads

  • Resources should never use numeric IDs—Only UUIDs or strings should be used.
  • Paths should use kebab-case (lowercase with hyphens), such as /v1/sites.
  • Paths should name the resource collection in plural form, such as /v1/sites.
  • Verbs should not be used in path names; the HTTP method describes the action.
  • GET, HEAD, and DELETE requests should not have a request body.
  • In payloads, all keys must use snake_case, such as site_id.
  • All API responses must be in JSON format.

The path of a route should describe the resource but never the action. For example, /v1/sites is correct, but /v1/get-sites is not.

Date Formatting

Dates or timestamps should follow the format in the user's JWT datetime_format claim. If datetime_format is not available, default to d M Y H:i:s. Timestamps should use the timezone from the user's JWT timezone claim. If timezone is not present, use UTC.

GET/v1/sites

Collections

When retrieving a collection of resources, the response should be an array of objects, even if there is only one resource in the collection.

GET/v1/sites/{site_id}

Resources

When performing a GET and passing the resource ID into the path a single resource will be returned.

POST/v1/sites

Creating Resources

All fields must be present in the payload. If a field is not present, it should be set to null. POST requests return a 201 Created with the created resource in the response body.

PATCH/v1/sites/{site_id}

Partial Updates

Only fields that are being updated should be present in the payload. If a field is not present, it should not be updated. PATCH requests return a 200 OK response with the updated resource in the response body.

PUT/v1/sites/{site_id}

Full Updates

All fields must be present in the payload. If a field is not present, it should be set to null. PUT requests return a 200 OK response under normal circumstances with the updated resource in the response body.

DELETE/v1/sites/{site_id}

Deleting Resources

Delete requests should return a 204 No Content response.

Was this page helpful?