Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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!

share|improve this question
    
Was just watching this: oredev.org/2010/sessions/hypermedia-apis –  Oded Aug 11 '12 at 20:30
1  
@Oded - awesome video and it helped. Thanks! –  BestPractices Aug 11 '12 at 21:07
    
interesting question and in my opinion still an important one. Did you find some new ways to achieve what you wan't? –  zewa666 Feb 28 at 20:36

2 Answers 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.

share|improve this 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.

share|improve this answer
    
How is the API communicated in REST so that the consumer can clearly understand it? If a GET request will return an XML document with 20 different attributes, how are those 20 different attributes and their meanings communicated to the consumer of the API? –  BestPractices Aug 11 '12 at 20:45
2  
@BestPractices: Let me reverse the question. How does the consumer know the API endpoint on which he should issue the GET request? The answer is that it knows it. It should know it, otherwise it cannot contact the producer. Similarly, the consumer also ought to know the response types, response attributes, etc. That's why one of the most important qualities I value in an API is their documentation. An undocumented API is quite simply unusable. –  Charalambos Paschalides Aug 11 '12 at 21:55
    
What is the standard for documenting a REST API? –  BestPractices Aug 12 '12 at 14:12
    
There is no standard for this. I guess it's a too immature/controversial field for a standard :-). Check out this similar discussion. –  Charalambos Paschalides Aug 12 '12 at 14:22

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.