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.

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"
}