How to achieve a loosely coupled REST API but with a defined and well understood contract?

Question

I am new to REST and am struggling to understand how one would properly design a REST system to both allow for loose coupling but at the same time allow a consumer of a REST API to understand the API.

If, in my client code, I issue a GET request for a resource and get back XML, how do I know what to do with that xml? e.g. if it contains <fname>John</fname><lname>Smith</lname> how do I know that these refer to the concept of "first name", "last name"? Is it up to the person writing the REST API to define in documentation some place what each of the XML fields mean? What if producer of the API wants to change the implementation to be <firstname> instead of <fname>? How do they do this and notify their consumers that this change occurred? Or do the consumers just encounter the error and then look at the payload and figure out on their own that it changed?

I've read in REST in Practice that using a WADL tool to create a client implementation based on the WADL (and hide the fact that you're doing a distributed call) is an "anti-pattern". But I was planning to do this-- at least then I would have a statically typed API call that, if it changed, I would know at compile time and not at run time. Why is this a bad thing to generate client code based on a WADL?

And how do I know what to do with the links that returned in the response of a POST to a REST API? What defines this contract and gives true meaning to what each link will do?

Please help! I dont understand how to go from statically-typed or even SOAP/RPC to REST!

Answer 1

Having a loosely coupled architecture, like in the case of a REST API server and its corresponding client, implies that both parties understand and respect a common protocol and semantics.

If the API modifies the semantics of its response, the client needs to be aware of it, and acd on the response accordingly.

Having said that, tools evolve and change. Because of the nature of decoupled architecture, any modifications on the API producer should be reflected on the consumer. However, for practical reasons this is not always possible. Usually for really radical modifications, the producer will expose different API endpoints, reflecting the old and new API functionality. This basicall buys the consumer time, up to the point that the old API is completely deprecated.

Answer 2

What if producer of the API wants to change the implementation

The producer should supply versions of the API.

http://blogs.gartner.com/eric-knipp/2012/08/27/catalyst-debrief/

The majority of Web API initiatives leave versioning for later. I believe this is a dangerous idea for a variety of reasons. First and foremost, if you run just one version of an API you risk introducing a breaking change anytime you extend it. While you can potentially work around this with a very robust set of test cases (which I would strongly encourage), it is easy to paint yourself into a corner when you are unable to fix a bad implementation that seemed like a good idea at the time.

If you look at the Twitter REST API, you'll see a version number in the URL:

api.twitter.com/1.1/statuses/mentions_timeline.json

This allows the producer to change the output data format as the API evolves. Applications that consume the API would then publish updates as they move towards later versions of the API.

As far as how to know what each data key means, the API should be documented to show you (1) what will be returned & how it relates to their service and (2) the data and data format required to be sent to their service.