My guess is you are familiar with the phrase “If you have to ask, you can’t afford it”. Well, that’s not what I mean here. Let me show you what I’m actually getting at…
If They Have to Ask… Try this:
- Create a new Web API
- Get it up and running on some server or other
- Hand the single URL to a client dev and say: “There ya go!”
Is the API self-descriptive? Does it contain enough information in the responses to allow client devs to know what the API is for, what it is capable of and how they can make valid requests to the server and properly parse the responses?
Here are some questions for you:
- How many assumptions do you have about your API?
- Are these assumptions shared by client devs?
- All clients devs?
- Even ones who have never met you?
If your answer to any of those questions was “No” or “I’m not sure” then it’s likely that devs will need to ask you a thing or two about how to properly use your API. That’s no big deal, right?
…You Didn’t Afford It In everyday life, if people have to ask how to use a device (television remote, toaster etc.) then you can be sure that device is “poorly afforded” – it’s a case of weak design. We all know devices (especially electronics) that come with huge manuals and complicated explanations – and we all know what a bummer it is when that happens.
In this respect, your API is the same as any other consumer device. It should be “well afforded” – developers shouldn’t have to read the technical equivalent of War & Peace before they are able to successfully use your API.
Yes, you can supply detailed instructions in prose, provide a long list of possible methods, include lots of tables etc. These resources are helpful for devs but they can be daunting to read and cumbersome to maintain.
Another approach is to include this kind of information in a machine-readable format – and one that most devs will also understand quickly. This can be achieved by providing instructions (that get automatically updated whenever your API changes) via hypermedia controls in the response. Why write a Web page of documentation to tell devs to construct a URI and use that URI to execute an HTTP GET when you can just include that (and much more) information in your API responses?
Help your client devs out. Throw ’em a bone, here. Don’t make them read pages of documentation when you can just include simple run-time instructions as they’re needed.
In conclusion: If they have to ask, you didn’t afford it.
(Originally published on my personal blog.)