So as promised, I’m going to cover how we describe and guide a client through a REST service, as promised in my last blog post.
One of the first things I’d like to point out is the absence of the WSDL in REST services. So no WSDL, and knowing that RESTful services do not completely describe themselves, this leaves us with the following questions:
- How do we know the operations on the service?
- How do we know the format of the representations?
- How do we know the workflow?
If you carefully design your service URI’s and “connectedness” between resources, the consumers of a RESTful web services can start from the base URI of the service and navigate around the landscape of your service using the concept of HATEOAS and the OPTIONS verb. That’s the first and third problem solved, however, the one thing they are still missing is the format of the representations.
RESTful web services are still going to require human readable specifications of the representations passed between your service calls. The XML structures, the attributes, the value constraints, are all still left up to you as the service provider to communicate to your clients. Amazon present a good example of REST API documentation for the Amazon S3 solution, you can check this out here.
The less constraints you put on the format of the representations and the more clarity you can put to your clients on interpreting the representations, then the more agility you both have for absorbing change.
Don’t encourage clients to build domain objects based on your representations to deserialize on the wire, as this pretty much locks you in to not changing the representations – the moment the representation changes, the deserializers breaks, and clients won’t be happy.
Here’s an example of a SLA on service representations:
- All representations start with an opening header element that describe the URI’s that the current resources state can move to.
- All URI’s are provided in <link> elements, where the attribute “rel” identifies a short description of the relation of the link to the current representation.
An example representation that conforms to this SLA would look like:
<order> <header> <link rel="summary">http://myservice.com/orders/12345</link> <link rel="lines">http://myservice.com/orders/12345/lines</link> <link rel="confirm">http://myservice.com/order-confirmations/12345</link> </header> .... </order>
Do carefully consider the connectedness of resources to each other so that this leaves less for you to do in documentation. Also consider how consumable the service is from a client perspective. A service is much easier to read when things are described from a business naming perspective, for example, “PlaceOrder” as opposed to “CreateOrderHeader”. Lastly, are the names of your URI’s well representing the concepts and resources of the service?
Overall, keep it easy on the client, but be clear on what you strictly want to be in complete control to change to keep you agile for future changes and enhancements.