URI Space and Resource Representations

URIs

Each RESTful service specifies the resources which representations may be retrieved and manipulated by clients. Resources in the system must be identified by RFC 2396 URIs. Resource identifiers must be intuitive and should reflect the semantics of the entities that they identify. Appropriate resource identifiers provide context for a service request, increasing understandability of the API. Resources should be viewed hierarchically via their URI names, offering consumers a friendly, easily-understood hierarchy of resources to leverage in their applications. Here are some recommendations on designing the resource identifiers:

Leverage the hierarchical nature of the URI to imply structure
Use nouns over verbs in the path segments, use plurals for collection resource identifiers
Use lower-case, use underscores ('_') or hyphens ('-') for separating words as some environments may be case-insensitive
Keep URLs as short as possible, with as few segments as makes sense

Resource representations must be encoded in JSON, as specified in RFC 4627.

Resource Discovery Through Links – Applying HATEOAS

The uniform interface principle of the REST architectural style constrains the interface between clients and servers. Applying HATEOAS increases intuitiveness and discountability and eliminates the coupling between the server and client enabling independent evolvability. Applying HATEAOS implies that resource representations must contain hypermedia links which act as state transitions. However, HATEOAS must be carefully applied in order to avoid unnecessary complexity and network chattiness of the interface.

Currently, there are several open JSON-based hypermedia specifications (JSON Siren, HAL, Collection+JSON, Hyper+JSON, Hypermedia JSON) but they all lack simplicity and are not well fit for the concept of hypermedia link expansion. Hypermedia links would be best implemented based on some custom hypermedia format in order to enable resource expansion and minimize chattiness. For more information on the subject refer to: Customizing Resource Representations.

Common Resource Fields Type Definitions

Type	Description
Identifier	Identifier of the entity represented by a certain resource, expressed via string.
Link	Hypermedia links are used to model relationships between resources and drive application state. The links are expressed via relative RFC 2396 URIs with leading "/", where scheme, host and port are omitted and special characters ".
Expandable Link	Expandable hypermedia links represent hypermedia links that can be expanded with the fields of the resources that they refer to. The expandable links always contain a href field holding a reference to the linked resource and, in case of instance resource, id field holding the unique identifier of the entity that is represented by this resource. Various additional fields may be included depending on the representation of the linked resource end the link expansion constraints.
Discovery Link	Discovery links represent hypermedia links with embedded metadata that can be used for resource discovery. The discovery links always contain a href field holding a reference to the linked resource and may optionally contain a description field holding textural description of the linked resource and/or a method field specifying the HTTP method that needs to be used against the link.

Expandable Links

Field	Type	Resolution	Description
href	Link	mandator	Unique identifier of the resource represented by this link, resource self link. URIs of other resources in the URI space of this resource can easily be derived by the self link.
id	Identifier	optional	Unique identifier of the entity represented by this resource. The identifier is included in the representation only if this is a link to an instance resource. In case of a link to a collection resource this field is omitted.

Discovery Links

Field	Type	Resolution	Description
href	Link	mandatory	Unique identifier of the resource represented by this link, resource self link. URIs of other resources in the URI space of this resource can easily be derived by the self link.
description	String	optional	Textural description of the linked resource.
method	String	optional	HTTP method to be used against this link.

Common Resource Identification Fields

Instance resources which represent an identifiable entity in the system must contain identification fields that should be included in all resource representations transferred within the system. The identification fields may be used for resource filtering and qualification or performing quick searches by identifier, name or tags. The resource identification fields are listed in the table below, expandable links of instance resources would generally contain the href field and optionally some other identification fields such as id and gatewayId.

Field	Type	Resolution	Description
tags	String[]	optional	User defined collection of tags for the entity represented by this resource which can be optionally set and used for resource identification and quick searches of resources by a specified tag.
name	String	optional	User defined name of the entity represented by this resource which can be optionally set and used for resource identification and quick searches of resources by a specified name.
id	Identifier	optional	Unique identifier of the entity represented by this resource.
href	Link	mandatory	Unique identifier of this instance resource, self link. URIs of other resources in the URI space of this resource can easily be derived by the self link.
gatewayId	Identifier	optional	Unique identifier of the gateway that this resource is associated with, if there is such. If this resource represents an entity that is not associated with a gateway, then this field is omitted.