chapter 4. Service Contracts with REST
4.1. Uniform Contract Elements
The REST uniform contract is based on three fundamental elements:
1. resource identifier syntax – How can we express where the data is being transferred to or from?
2. methods – What are the protocol mechanisms used to transfer the data?
3. media types – What type of data is being transferred?
These elements are commonly represented using a triangle symbol, as shown in Figure 6.1. 


the relationship between URIs, URLs, and URNs is highlighted in Figure 6.2.
* URIs are simply sequences of characters that conform to the standardized syntax.
* URLs are URIs that can be used in requests. Referring to concepts in a way that can be used directly as a resource to send messages to its underlying service is so useful that most URIs used in REST service architectures are also URLs. This makes the terms somewhat equivalent, which is the reason they are often used interchangeably.
* URNs are URIs that can be used as unique identifiers for resources, such as business entities. 


Figure 6.2. How URIs, URLs, and URNs relate to each other.
For example is a URI because it conforms to the generic syntax. It is also a URL because we can use it as a resource identifier and invoke methods upon it. 

7.2. Design Goals
Increased Intrinsic Interoperability

Services within a given boundary are designed to be naturally compatible so that they can be effectively assembled and reconfigured in response to changing business requirements.

– performance / scalability / modafiability / relialibility
Increased Vendor Diversity Options
A service-oriented environment is based on a vendor-neutral architectural model, allowing the organization to evolve the architecture
in tandem with the business without being limited to proprietary vendor platform characteristics.

– portability
Increased ROI
Most services are delivered and viewed as IT assets that are expected to provide repeated value that surpasses the cost of delivery and ownership.
– simplicity / modafiability

7.3. Composition Hierarchies and Layers
As explained in previous chapters, service-oriented analysis and design approaches tend to naturally partition solution logic into logical service layers based on service models. Figure 11.7 illustrates how a complex REST-based service composition can be comprised of collections of entity and utility services that compose each other under the direction of parent composition logic encapsulated by a task service.

Figure 11.7. Tiers of services based on established service models form a service composition hierarchy. Within such a hierarchy, service capabilities are invoked across task, entity, and utility layers that correspond to the following individual patterns:
* Process Abstraction
* Entity Abstraction
* Utility Abstraction
Each of these patterns is based on the fundamental Service Layers

Examples of interactions that may violate Stateless include:
• cross-service transaction (such as those that emulate ACID transactions)
• event-driven interactions (such as publish-subscribe)

Chapter 8. Advanced Service Composition with REST
Cross-Service Transactions with REST
Transaction-related Problems can include(Problems )
1. resource locks become exhausted or significantly limit concurrent access to a resource
2. transactions time out, requiring that they be re-invoked
3. the behavior of complex transactions can be unpredictable and may require consumers to wait an inordinately long time for completion
REST-Friendly Atomic Service Transactions(Solutions)
By remaining compliant with Stateless , we can develop a service composition architecture able to provide limited two phase commit capabilities for the creation of new resource state.
The basis of this model is as follows:
1. A service consumer makes a request to the service to create a new resource.
2. The service accepts the request and creates the resource, but leaves it in an inactive state.
3. The service provides instructions as to how to activate the new resource.
4. When the consumer has confirmed it is able to create as many new resources as required, it transitions each to an active state.

Phase 1: Initialize
The composition logic registers the Store and Confirm Transaction with a transaction coordinator service.
For example, the consumer sends the transaction coordinator: POST
…and the transaction coordinator returns back to the consumer:
201 Created
The link to the transaction resource will be later used to keep track of which resources are involved in the transaction, and to collect the necessary information to perform the third phase.

Phase 2: Reserve
The composition logic executed by the composition controller interacts with the composition member resources. The new required entities are created but left in an intermediate, temporary state. This intermediate state is associated with a confirmation resource identifier generated by the composition member and forwarded by the composition controller to the transaction coordinator resource.
For example, the consumer sends to the service: POST
The service replies with a link to the confirmation resource identifier, which can be included as metadata or extracted from the response payload:
booking/BRF134422/confirmed; rel=”store-and-confirm”
The consumer then forwards the confirmation resource identifier to the transaction coordinator and associates it with the pending transaction:
REST-Friendly Compensating Service Transactions
The lock contention and state memory consumption demands of two- phase commit transactions can be too burdensome for an IT infrastructure when having to support long-running transactions.
The standard pattern for addressing this is Compensating Service Transaction whereby we sacrifice the atomicity of Atomic Service Transaction by replacing the pessimistic PREPARE and COMMIT

Figure 12.1. A service subscribes to an event via the Event Manager. When the event occurs later, the publisher service sends notifications to the Event Manager that forwards notifications to subscribed consumers.

Event-Driven Messaging can be applied using REST features in a number of ways.
NOTIFY method can be add to the uniform contract in order to inform both the Event Manager and subscribed consumers that a notification has occurred.
SUBSCRIBE method could also be created, or a POST request could be issued to the Event Manager resource to create a new subscription resource to register subscribers.
DELETE request to the subscription resource could correspondingly cancel the subscriber’s interest. An example of this mapping into the Event Manager service contract can be seen in Figure 12.2.

Figure 12.2. A sample service contract for an Event Manager service.
Advantage to this approach is that
it can establish some level of security control. For example, subscription requests can include a resource identifier that the Event Manager may be designed to automatically send notification messages to.
If the method used to notify subscribers of new events was a POST or a PUT, a malicious subscriber could substitute its own notification capability with another service’s vulnerable service capability and the Event Manager would blindly invoke that method.
The use of the NOTIFY method for notification messages can prevent the Event Manager from accidentally triggering an unsafe service capability in this type of situation. We can define NOTIFY as being a safe method with no negative side-effects attributable to the caller.
This straightforward mapping approach does introduce some

It may prevent media type negotiation from being supported, and tends to bypass the conventional service caching infrastructure by creating two lines of traffic for data exchange.
The first is the usual GET requests that pass through the caching infrastructure and the second is the stream of notifications sent back to service consumers via the Event Manager.
The standard GET request in a typical uniform contract includes the ability to select between alternative media types for the response message. Therefore, without including GET into the mechanism, it becomes necessary for SUBSCRIBE to start to support this and other

Response messages from the service to its consumers are explicitly labeled as cacheable or non-cacheable. This way, the service, the consumer, or one of the intermediary middleware components can cache the response for reuse in later requests. The Cache constraint builds upon Client-Server and Stateless with a requirement that responses are implicitly or explicitly labeled as cacheable or non-cacheable. Requests are passed through a cache component, which may reuse previous responses to partially or completely eliminate some interactions over the network (Figure 5.3).

in another word :

cachable or non-cachable : This way the service, th consumer or any of the intermediary middleware components can cache the response for reuse in the later request

Response : maybe cached by the consumer to avoid resubmitting the same requests to  the service.

Endpoint Redirection
Redirection is a natural part of Web architecture that can be leveraged to allow for the evolution of Web-based resources without compromising consumer programs designed to access those resources (Figure 14.2).
The simple but effective feature of redirection is captured by the Endpoint Redirection pattern as a technique that can be applied to service composition design.
The assumption is that even when a service endpoint becomes stale, a placeholder service remains active in the old resource location so that out-of-date consumers can be informed about the new endpoint as they attempt to interact with the old one.


figure 14.2. Consumers that access stale service endpoints do not have to be upgraded as they can be simply redirected to the updated service endpoint. Redirection built into service contracts along with predefined redirection rules built into service consumers allow service capabilities to evolve without needing to immediately upgrade service consumers that still hold stale references.
Related Patterns
* Lightweight Endpoint

Related Service-Oriented Computing Goals
* Increased Organizational Agility
* Reduced IT Burden

Entity Linking
The application of this pattern enables the runtime communication of entity relationships via links provided by the service to the service consumer in response messages (Figure 14.3).
Inspired by the HTTP feature-set and the use of hyperlinks, Entity Linking can help reduce consumer-to-service coupling while increasing entity relationship intelligence available at runtime.

Figure 14.3. Services that expose identifiers of related entities to service consumers are able to be used in a wider variety of compositions. In this example, related business entities are discovered by following links between resources. The Report Aggregator service is able to look up any invoice fields that it might require and is not limited to a predefined set within the standard report. The Invoice Printer service is able to then cross-reference invoice and customer records in order to print mailing labels.

Lightweight Endpoint

This pattern is inspired by a resource-centric view of business entities and artifacts involved in business automation or that relate to business automation requirements. These are the same types of artifacts that form the basis of entity services.

This pattern complements Reusable Contract because business-centric resources naturally provide business contexts for use in conjunction with a (business context-free) reusable contract providing abstract functions.

Related Patterns
* Contract Denormalization
* Concurrent Contract
* Reusable Contract
* Uniform Contract
Related Service-Oriented Computing Goals
* Increased Intrinsic Interoperability
* Increased Business and Technology Alignment
* Increased ROI
* Increased Organizational Agility
* Reduced IT Burden