There are four parts to the URI of a REST service: the host, context, API version, and the desired resource.

{host}/{context}/{api-version}/{resource}

Each part may be comprised of more granular elements and will be described in their respective sections.

• Each of the URL elements listed above MUST use snake_case

Host

The host will be in the following format:

The –qa indicator represents a non-production deployment.  When no indicator is present then the stage is production.

Context

The API context is used to determine which API an incoming request is attempting to access. The API Context MUST be unique and snake_case. When viewing APIs in the store and publisher the API Name is used. The API Name should be unique and human friendly. It is our recommendation that the context be a URL-friendly version of your API Name. Often we suggest removing special characters and setting it to lower case. Some long API Names can also be abbreviated. It should be clear which API Name and API Context is referencing, so when a developer is reading code and finds the URL that is invoked, they can find that API in the store.

API Version

The API version is used to determine which iteration of an API an incoming request is attempting to access. It is used in conjunction with the API context.  API version indicates breaking change in the interface (request or response) or functionality that prevents existing consumers from consuming this API successfully.

• Version only when needed. A new version of API also requires multiple runtime binaries and many times, backend database changes.

• Work with clients to see if they can be upgraded without increasing the version

• Support at the most 2 versions

• Version if the response has breaking change as well.

How to version:

There are different ways to version an API. Various techniques are based on indicating version number in:

• Headers

• URLs

• Headers & URLs both, using a Hybrid approach. Use the latest version by default unless a specific version is provided in the header or in URL

It is recommended to use URL based versioning as it specifically indicates what version is being used by the consumer. A version number should be appended to the host to allow for versioning of the resources.

Version Format:

It is recommended to format the version like: v1, v2, etc.  Optionally you can omit the “v” or include a minor version like: v1.2, 1.2, etc.  However, minor versions shouldn’t cause breaking changes so minor versioning in the url is discouraged.

Resource

The resource URL element specifies an entity in the current context.  A resource by itself represents a collection of entities. You can refer to a single entity by specifying a unique identifier.

General Conventions

• Resources MUST use snake_case

• Resources SHOULD be nouns and not verbs

• Resources SHOULD be plural

• Concrete resources are better than abstract

• e.g. /dogs better than /animal

Single Entity Resource

A specific resource entity can be targeted by adding the identifier to the URL.  For example:

The identifier MUST uniquely identify a specific resource entity.

Compound Resource Identifiers

If more than one identifier is needed to identify a resource, they MUST be concatenated with commas:

Qualified Resource Identifiers

When there are multiple types of resource identifiers, it is a good practice to qualify the identifier.

Sub Resources

Sub resources are used to interact with entities that can be uniquely identified by a higher level resource and have a direct relationship to the higher level resource.  For example:

This sub resource could be used to create a comment and associate it with an article.

Sub resources can also be identified with the same rules as top-level resources. For example:

Query Parameters

Query parameters can be used to specify the desired format of a response, for example: filtering, paging, sorting, etc.  Query parameters MUST be camelCase.

It is recommended to use the HAL specification to represent responses in json or xml.  HAL provides a set of conventions to express HATEOAS linking consistently.

• HAL Specification
• HAL Primer

Content negotiation

Content negotiation allows an API to provide multiple representations of a resource with the same URL.  Two headers primarily used to enable this are Accept and Content-Type.

• Accept - used by the client to specify which representation type is preferred in the response when there are multiple options available.
• Content-Type - used by both the client and API to specify the representation of the request / response bodies.

Single resource

Single entity resources are targeted with urls that end in a unique identifier.  For example:

Resources are composed of name / value pairs where the values can be basic data types, objects, or arrays.

Basic data types

Strings:

{
	"title" : "REST API Guidelines"
}

Numbers:

{
	"integer" : 1234,
	"negativeInteger" : -1234,
	"decimal" : 1234.01,
	"scientificNotation" : 1.2E+3
}

Boolean:

{
	"flag" : true
}

Date/Time:

Date and time formats MUST follow the ISO8601 format specified in RFC3339 Section 5.6.  Examples:

{
	"date" : "2019-03-25",
	"timeLocal" : "13:30:57",
	"timeUTC" : "13:30:57Z",
	"timePSTOffset" : "13:30:57-08:00",
	"dateTimeUTC" : "2019-03-25T13:30:57Z",
	"dateTimePSTOffset" : "2019-03-25T13:30:57-08:00" 
}

Objects

Resources can have attributes values represented as other objects.  If object is a sub-resource, meaning that can be specifically accessed via a URL, then it SHOULD be listed under the _embedded attribute following the HAL specification.  A self link should be provided as well for easy access to the sub-resource.

Arrays

Attributes values can also be arrays.  Arrays are collections of homogeneous values.  The values can be basic data types or objects.

Links

Links are used to provide possible actions that can be made on a resource given its current state.  More information can be found later in this document in the Links section.

Collections of resources

Resource collections are targeted with URLs that don’t specify a single resource with an identifier.  For example:

Even if a filtering option is provided that results in a single resource, an array of resources should still be expected by the user agent.  Collections of resources SHOULD be listed under the _embedded attribute, following the HAL specification, indicating that individual resources can be directly accessed via a self URL.

If the resources in the collection are large, then a reduced representation can be used that only contains the minimum attributes necessary for identification.  The reduced resources MUST be accompanied by a self link to retrieve the full resource by itself.

Paging

It is recommended to provide paging options on large collections of resources to let the user agent limit the number of resources retrieved at one time.  Additionally, links SHOULD be provided to facilitate the traversal of the paged collection.

More information can be found later in the document under the Pagination section.

Sorting

It is recommended to provide sorting options on large collections of resources.  Even if sorting options are not provided, it is recommended to specifically order the collection by default for consistent responses.

More information can be found later in the document under the Sorting section.

Filtering

It is recommended to provided filtering options on large collections of resources.

More information can be found later in the document under the Filtering section.