Resource names (#122)

Most APIs expose resources (their primary nouns) which users are able to create, retrieve, and manipulate. Additionally, resources are named: each resource has a unique identifier that users use to reference that resource, and these names are what users should store as the canonical names for the resources. This AIP also addresses resource attribute names.

Scope

While this document is focused on http apis. These rules should apply to all APIs, including configuration files (like kong.yaml) and other API interfaces. Diverging from these rules should be the exception and API designers should provide a rationale for that exception (.e.g: API is directed to Kubernetes user and Kubernetes resource naming conventions will be applied).

Guidance

All resource names defined by an API must be unique within that API. Resource names are formatted according to the URI path schema, but without the leading slash:

/v1/services/cats
/v3/users/ada

When a resource name includes more than one word, its name is in kebab-case.

/v1/konnect-services/domestic-cats
/v3/users/ada-lovelace

Kong APIs should prefer lowercase resource names such as services and users. Any other case (upper, title, camel, etc.) should be the exception and API designers should provide a rationale for that exception.

Field names

Field names are all lower case. When a field name includes more than one word, its name is in snake_case.

GET /v1/services/domestic-cats
{
  "name": "Spot",
  "primary_color": "black",
  "secondary_color": "brown",
  "breed": "American Short Hair"
}