Skip to content

Latest commit

 

History

History
169 lines (121 loc) · 5.33 KB

resources.adoc

File metadata and controls

169 lines (121 loc) · 5.33 KB

Resources

{SHOULD} avoid actions — think about resources

REST is all about your resources, so consider the domain entities that take part in web service interaction, and aim to model your API around these using the standard HTTP methods as operation indicators. For example, rather than creating a specific action for completing a certification campaign, prefer to use PATCH to update the completed status of the campaign.

Request

PATCH v1/campaigns/{campaignId}

Body

{
    “completed”: true
}

Sometimes, standard HTTP methods aren’t specific enough to indicate the action you wish to perform on a resource, or there is complex business logic on the back end that can’t be satisfied by PATCHing a single field. In these cases, it is advisable to use the following URI format for specific resource actions:

Request

POST v1/campaigns/{campaignId}/remediation-scan

{SHOULD} model complete business processes

TBD

{SHOULD} define useful resources

As a rule of thumb resources should be defined to cover 90% of all its client’s use cases. A useful resource should contain as much information as necessary, but as little as possible. A great way to support the last 10% is to allow clients to specify their needs for more/less information by supporting filtering and embedding.

{SHOULD} keep URLs verb-free

The API describes resources, so the only place where actions should appear is in the HTTP methods. In URLs, use only nouns. Instead of thinking of actions (verbs), it’s often helpful to think about putting a message in a letter box: e.g., instead of having the verb cancel in the url, think of sending a message to cancel an order to the cancellations letter box on the server side.

{MUST} use domain-specific resource names

API resources represent elements of the application’s domain model. Using domain-specific nomenclature for resource names helps developers to understand the functionality and basic semantics of your resources. It also reduces the need for further documentation outside the API definition. For example, "sales-order-items" is superior to "order-items" in that it clearly indicates which business object it represents. Along these lines, "items" is too general.

{MUST} use URL-friendly resource identifiers: [a-zA-Z0-9:._\-/]*

TBD

{MUST} identify resources and sub-resources via path segments

Some API resources may contain or reference sub-resources. Sub-resources should be referenced by their name and identifier in the path segments as follows:

/resources/{resourceId}/sub-resources/{subResourceId}

In order to improve the consumer experience, you should aim for intuitively understandable URLs, where each sub-path is a valid reference to a resource or a set of resources. For instance, if /partners/{partnerId}/addresses/{addressId} is valid, then, in principle, also /partners/{partnerId}/addresses, /partners/{partnerId} and /partners must be valid. Examples of concrete url paths:

/shopping-carts/de:1681e6b88ec1/items/1
/shopping-carts/de:1681e6b88ec1
/content/images/9cacb4d8
/content/images

Note: resource identifiers may be build of multiple other resource identifiers (see [241]).

Exception: In some situations the resource identifier is not passed as a path segment but via the authorization information, e.g. an authorization token or session cookie. Here, it is reasonable to use self as pseudo-identifier path segment. For instance, you may define /employees/self or /employees/self/personal-details as resource paths —  and may additionally define endpoints that support identifier passing in the resource path, like define /employees/{emplId} or /employees/{emplId}/personal-details.

{SHOULD} consider using (non-)nested URLs

If a sub-resource is only accessible via its parent resource and may not exist without parent resource, consider using a nested URL structure, for instance:

/shoping-carts/de/1681e6b88ec1/cart-items/1

However, if the resource can be accessed directly via its unique id, then the API should expose it as a top-level resource. For example, customer has a collection for sales orders; however, sales orders have globally unique id and some services may choose to access the orders directly, for instance:

/customers/1637asikzec1
/sales-orders/5273gh3k525a

{MUST} not use sequential, numerical IDs

Numerical, sequential IDs are considered a security risk because malicious actors can enumerate through the IDs to obtain unauthorized information. API producers must use GUIDs or natural keys that aren’t sequential.

{SHOULD} limit number of resource types

TBD

{SHOULD} limit number of sub-resource levels

There are main resources (with root url paths) and sub-resources (or nested resources with non-root urls paths). Use sub-resources if their life cycle is (loosely) coupled to the main resource, i.e. the main resource works as collection resource of the subresource entities. You should use ⇐ 3 sub-resource (nesting) levels — more levels increase API complexity and url path length. (Remember, some popular web browsers do not support URLs of more than 2000 characters.)