diff --git a/rest-api-guidelines/quality/evolution/naming-conventions.md b/rest-api-guidelines/quality/evolution/naming-conventions.md index c6d12be..6026dcd 100644 --- a/rest-api-guidelines/quality/evolution/naming-conventions.md +++ b/rest-api-guidelines/quality/evolution/naming-conventions.md @@ -13,6 +13,14 @@ Every identifier **MUST** be in American English and written in `lowercase`. An Every URI **MUST** follow the General Rules except for the `camelCase` rule. Instead, a hyphen \(`-`\) **SHOULD** be used to delimit combined words \(kebab-case\). Besides, a URI **MUST NOT** end with a trailing slash \(`/`\). +Plural nouns SHOULD be used in the URI where appropriate to identify collections of data resources (e.g. ``/orders``, ``/products``). + +An individual resource in a collection of resources MAY exist directly beneath the collection URI. (e.g. ``/orders/{order_id}``). + +Sub-resource collections MAY exist directly beneath an individual resource. This should convey a relationship to another collection of resources (e.g. ``/orders/{order_id}/items``). + +Sub-resource individual resources MAY exist, but should be avoided in favor of top-level resources. (e.g. ``/orders/{order_id}/items/{item_id}``). + #### Example A well-formed URI: