Naming Conventions
#
Name of the data source to represent the data#
MUST Use lowercase separate words with hyphens for Path SegmentsExample:
This applies to concrete path segments and not the names of path parameters. For example {shipment_order_id}
would be ok as a path parameter.
#
MUST Use snake_case for Query ParametersExamples:
#
MUST Pluralize Resource NamesUsually, a collection of resource instances is provided (at least API should be ready here). The special case of a resource singleton is a collection with cardinality 1.
#
MUST use Outsider Understandable Property and Variable NamesProperty and variable names should not contain acronyms or word shortenings that require any project or database specific knowledge to decipher.
Examples:
The shortenings like id
and ref
are considered acceptable as they are universally understood.
#
MUST use camelCase Property NamesData formats - camel casing.
#
MUST Pluralise Array NamesData formats - array names.
#
MUST Avoid Trailing SlashesThe trailing slash must not have specific semantics. Resource paths must deliver the same results whether they have the trailing slash or not.
#
MUST Stick to Conventional Query ParametersIf you provide query support for searching, sorting, filtering, and paginating, you must stick to the following naming conventions:
q
โ default query parameter (e.g. used by browser tab completion); should have an entity specific alias, like skusort
โ comma-separated list of fields to define the sort order. To indicate sorting direction, fields may be prefixed with+
(ascending) or-
(descending), e.g. /sales-orders?sort=+idfields
โ to retrieve only a subset of fields of a resource.embed
โ to expand or embed sub-entities (ie.: inside of an article entity, expand silhouette code into the silhouette object). Implementingembed
correctly is difficult, so do it with care.offset
โ numeric offset of the first element on a page. See pagination section.limit
โ client suggested limit to restrict the number of entries on a page. See pagination section.