In his talk on Some REST Design Patterns (and Anti-Patterns), Cesare Pautasso explains, “REST architectural style is simple to define, but understanding how to apply it to design concrete REST services in support of SOA can be more complex.”
Several SOA Design Patterns:
- Uniform Contract
- Endpoint Redirection
- Content Negotiation
- Idempotent Capability
In this post, you will learn the design methodology, walk through a step by step scenario where the client and server trade information to perform a set of actions, and you will learn more about the SOA design patterns.
In Choosing Between RESTful Web Service, SOAP, you learned that Representational State Transfer (REST) is an architecture style or design pattern for creating web services which allow anything connected to a network to something else on the network using Hypertext Transfer Protocol (HTTP).
Web Services expose data and functionality through resources identified by a Uniform Resource Identifier (URI).
REST has a uniform interface where clients perform stateless interaction with resources using a fixed set of verbs, typically GET (read), PUT (update), DELETE, POST.
You can have multiple representations of the same data.
Hyperlinks model resource relationships and valid state transitions for dynamic protocol description and discovery.
- Identify resources to be exposed as services (e.g., yearly risk report, book catalog, purchase order, open bugs, polls and votes)
- Model relationships (e.g., containment, reference, state transitions) between resources with hyperlinks that can be followed to get more details (or perform state transitions)
- Define “nice” URIs to address the resources
- Understand what it means to do a GET, POST, PUT, DELETE for each resource (and whether it is allowed or not)
- Design and document resource representations
- Implement and deploy on Web server
- Test with a Web browser
(Illustrations from SOA2010 SOA with REST)
Although there are four methods, you can add more resources, such as an author. And you can have multiple representations.
Let’s create a simple example in a polling scenario.
in our scenario, you have polls and votes. It’s a containment relationship where you have number of polls in which you have a number of votes.
The URIs embed the identifiers of child instance resources.
POST on the container is used to create child resources.
PUT/DELETE us used for updating and removing child resources.
Step 1. Create a poll
In the first step, you create poll. In this case, we will use XML in the body. But you can also use JSON.
In this case, the poll was created using POST with the possible options that the user could select. The server returns a 201 response with the location of the poll and its identifier.
Step 2. Reading the poll
The client can then send a request to the server to read the poll.
|<votes href="vote" />|
p>The poll with its identifier are retrieved with 200 OK in the response. The response body includes the options and the reference for the votes.
Step 3. Vote in a particular poll
In this step, you would post the data and return that the data vote was created. The response includes the location of the vote.
Step 4. Retrieve votes
You can then retrieve the votes.
Step 5. Update a particular vote
You can now let your user change their mind. In this case, use a PUT to update the particular vote. Note that the URI goes to vote/1.
Step 6. Retrieve
You can then retrieve the poll results again.
Step 7. Delete the Poll
You can then use the DELETE verb to delete the poll.
Step 8. Retrieve a poll that has been deleted
The server returns an 404 Not Found error because the poll has been deleted.
|404 Not Found|
How can consumers take advantage of multiple evolving endpoints? You need to keep your consumer up to date with respect to evolving contracts.
In the previous example, you saw how a Uniform Contract provides for Create, Read, Update, and Delete.
|CREATE||POST||Create a sub resource|
|READ||GET||Retrieve the current state of the resource|
|UPDATE||PUT||Initialize or update the state of the resource for a given URI|
|DELETE||DELETE||Clear a resource, after the URI is no longer valid|
POST vs GET
GET is a read-only operation. It can be repeated without affecting the state of the resource and can be cached.
NOTE: This does not mean that the same representation will be returned every time.
POST is a read-write operation and may change the state of the resource and provoke side effects on the server.
POST vs POST
How should you create a resource?
Solution 1. Let the client choose a unique ID
The downside of this is that how are you sure the client creates a unique identifier?
Solution 2. Let the server compute the unique id
|301 Moved Permanently|
The downside of this is that duplicate instances can be created if requests are repeated due to communication issues.
How do you provide the consumer with information so they can adapt to changes in your service. For example, you may want to change the structure of your data. It may not be possible to replace all of your old endpoints simultaneously.
In that case, you can automatically refer your consumers that access the stale endpoint to the current identifier.
|301 Moved Permanently|
HTTP supported endpoint redirection using a combination of the 3xx status codes and standard headers. For example, instead of using 301, you could provide 307 Temporary Redirect:
307 Temporary Redirect Location: /newUri
How can service consumers support new consumers without changing their contract? How can you change the content and data representation formats?
You want your Web Service to provide for loose coupling, increased interoperability, and increased organizational agility.
You can allow the client to negotiate the message format in a single message. The client can list the set of understood formats (MIME types). Then the server chooses the most appropriate and send the reply (or a 406 error if none can be found.)
|Accept: text/html, application/xml, application/json|
You can perform content negotiation across different dimensions.
|Accept-Language:||en, fr, de, es||Content-Language:|
|Charset parameter of the Content-Type header|
Additional REST Patterns
- Entity Linking
- Distributed Response Caching
- Idempotent Capacity
- Message-based State Deferral
- Message-based Logic Deferral
- Consumer-Processed Composition
For more patterns, see SOAPatterns.org.
Slideshare: SOA with REST