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.

When working with a web based restful api what resources would you like to work with from the beginning when developing a system against it?

  • Web based documentation?

  • Working example? Simple? Complex?

  • An SDK which abstracts away some of the details and allows in depth development straight away?

  • All of the above?

With your answers if web sites of examples are available that would be cool.

Appreciate all the help in advance.

share|improve this question
add comment

1 Answer

I want the API doc first. I'm not particular about the format. If you tell me to GET api/version.json, and that returns {"version" : "1.0"}, I think I can handle that in any language. Note: I specifically chose a version as my first example because I just had a system change its API on me and a similar API version query saved me a lot of headache. If you return html, xml, or json, I expect some sort of statement about what can and cannot be depended on structurally. This need not be formal, but I certainly appreciate it when it is. If you choose error responses for certain common cases, state it. Does invalid input in a POST cause a 400? Tell me.

I expect the API to be properly covered by documentation. This seems to be a more reasonable expectation than code example coverage.

Then I want samples of increasing complexity. But since this is a REST API, I guarantee that if you choose your example in python, I'll be using java. Choose java and I'm a ruby programmer. Choose ruby, and I use nothing but curl. Choose curl, and you're probably needing a bit of therapy.

I've never expected complete coverage of an API with samples, but it's nice to have.

If you gave me an SDK which abstracted the details, I'd use it as a detailed example, and might even use the SDK. But that's a lot of responsibility for you. Take ActiveMerchant, for example. I would use that for credit card processing. I work for PayJunction, so this isn't very hypothetical. But I would use it because it abstracts multiple payment APIs, not because it abstracts PayJunction's. Furthermore, I wouldn't expect PayJunction to make such a nice and flexible SDK (because their use case probably doesn't involve migrating the system away from using their particular service). I would expect more features out of a single-vendor solution, though.

Yahoo has several web services that can be thought of as simple Restful APIs, but they seem to be moving in a direction that some may not like. I used their tag API while working for a book-club site to pre-seed their content with tags based on the text descriptions of the books. Unfortunately, the site has changed considerably, so I don't even know if that is still a good example.

share|improve this answer
    
Thanks for your response. I like the idea of the version call although this might open a "how do we version an api?" can of worms :-) –  WestDiscGolf Dec 7 '11 at 13:51
    
Some places maintain old api versions and the programmer provides the version they are coding against. Some just have an api string and the programmer knows when it's time to expect breakage and go back to the docs. The latter is much easier on you. –  ccoakley Dec 7 '11 at 16:08
add comment

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.