REST Service Capabilities and REST Service Contracts
Uniform contract methods are extremely generic and multi-purpose. Therefore, they have little meaning beyond basic, high-level functions (such as Get Something or Update Something). For this reason, a uniform contract alone does not constitute a REST service contract.
The high-level method of the uniform contract invoked by the service consumer determines the parent context of the service consumer request (such as Get Something) and the provided resource identifier determines the specific function requested by the service consumer (such as "Customer Record Data for ID C081"). Together, these two parts of the service consumer request message give the REST service what it needs to carry out a specific function (such as Get Customer Record).
This means that:
- a REST service capability can be considered a combination of a uniform contact method and resource identifier
- a REST service contract establishes a functional context that encapsulates one or more REST service capabilities associated with the functional context
Earlier we introduced the symbol used to distinguish a REST service contract from a non-REST service contract. Throughout this Website, the notation established by this symbol is used to express REST service capabilities as combinations of HTTP methods and resource identifiers.
As further reiterated in Figure 1, each service capability is expressed on one or more grouped lines where the single uniform method precedes the resource identifier, expressed as a URL (or a URI template).
Figure 1 - A non-REST service contract (left) alongside a REST service contract (right). Note how REST-compliant service contracts are denoted with a triangle annotation to indicate their dependency on the uniform contract.
The service contracts displayed in Figure 1 provide minimal information about the service capabilities. This concise form of notation is typically used as a starting point during service modeling processes as part of early analysis project stages. To indicate the input data required by a service capability, a more detailed variation of the notation can be used, as shown in Figure 2.
Figure 2 - Both REST and non-REST service capabilities can be further detailed with input data information. In these examples, the id value represents the input expected by each service capability.
When depicting REST service contracts is runtime scenarios, the input data placeholder can be replaced with the actual expected input data value, as illustrated in the next sections.
Media type support represents a characteristic of a service capability. Although it is less common, media types may also be included in this notation by appending allowable media types to the service capability information. When doing so, it may be preferable to use a system of condensed codes to represent the list of media types supported by a given service capability.