Working with a restful Api; what resources would you like available to start with?

Question

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.

Answer 1

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.