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

restweb services

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!

Best Answer

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.

Related Topic