MUST pluralize resource names [17]

The base path is typically the name of the resource, which is typically a business object as defined in the business object model. The resource is represented in its plural form because the base path acts on the collection of the resource and not an individual resource.

MUST use kebab-case for path segments [18]

Use hyphen in API path for readability when the parts of the path are not hierarchal. If the parts of the path are hierarchal then use slashes.

MUST use lowerCamelCase for query parameters [19]

Just as with the JSON fieldnames the query parameters should be written in lowerCamelCase.

SHOULD use sub resource path when creating a resource based on another resource [20]

When creating a resource based on another resource, we use the path: POST /resource1/{id}/resource2 This means it’s an operation of the “source” resource API instead of the “target” resource API. This allows for specifying a body for resource2 as well as providing the identifier for resource1.

Examples:

POST salesquotations/{id}/salesorders

POST salesrequests/{id}/salesquotations

SHOULD model resources in composition relations as sub resources [21]

In a composition relation the sub-resources lifecycle is tied to the lifecycle of the parent resource i.e.. the sub-resource is removed when the parent object is removed. Like the relation between order and lines. Lines cannot be identified without an order and must be part of an order. Examples:

GET orders/v1/123/lines (Retrieving the lines of an order)

GET orders/v1/123/lines/2 (Retrieving a specific order line)

POST orders/v1/123/lines (Creating a new order line on an order)

PATCH orders/v1/123/lines/1 (Updating fields of a order line)

PUT orders/v1/123/lines/1 (Updating a specific order line)

MUST make a separate API for resources in a aggregation relation [22]

In an aggragation relation the lifecyle of the subresource is detached from the lifecycle of the parent resource ie. if the parent resource is deleted the subresource remains. Like a sales quotation and a sales order.

Can only be used to create sales orders based on the specific sales quotation. A separate sales orders API must be used to update the sales order Examples:

POST salesquoatations/v1/123/salesorders (Creating new subresources based on the parent resource is allowed)

GET salesquoatations/v1/123/salesorders (Retrieving the aggregate subresources is not allowed)

GET /salesorders?salesQuotation=123 (Retrieving sales orders for a sales quodation via separate API)

PUT salesquoatations/v1/123/salesorders/123 (Updating the aggregate subresource is not allowed)

MUST NOT nest collections directly under collections [23]

This must always be nested under the resources.

GET activityprojects/v1/externaltasks/456 (Creating new subresources based on the parent resource is allowed)

GET activityprojects/v1/123/externaltasks/456 (Nest collections directly under collections is not allowed)

MUST stick to conventional query parameters [89]

If you provide query support for searching, sorting, filtering, and paginating, you must stick to the following naming conventions:

sort: comma-separated list of fields to define the sort order. Indicate sorting direction with asc (ascending) or desc (descending), e.g. /sales-orders?sort=id_asc.

fields: field name expression to retrieve only a subset of fields of a resource. See ## SHOULD support partial responses via filtering [51] at Performance

next_cursor: an opaque pointer to a page, never to be inspected or constructed by clients. It usually (encrypted) encodes the page position, i.e. the identifier of the first or last page element, the pagination direction, and the applied query filters to recreate the collection. See ## SHOULD use cursor-based pagination [60]. at Pagination

limit: client suggested limit to restrict the number of entries on a page. See ## SHOULD use cursor-based pagination [60]. at Pagination

offset: Used in offset-based pagination [90] Offset is the number of records that need to be skipped

next: Used in offset-based pagination [90] The API will return the next page of data.

previous: Used in offset-based pagination [90] The API will return the previous page of data.