if they have to ask, you didn't afford it.

2013-03-16 @ 20:10#

my guess is you are familiar with the phrase: "If you have to ask, you can't afford it." that's not what i mean here. let me show you...

if they have to ask...

try this:

  1. create a new Web API
  2. implement it on some server - up and running
  3. hand the a single URL to some 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 client devs can make valid requests to the server and properly parse the responses?

here are some questions for you...

  1. how many assumptions do you have about your API?
  2. are these assumptions shared by client devs?
  3. all clients devs?
  4. even ones who have never met you?

if the answer to any of those questions is "no" or "i am not sure" then it is likely that someone will need to ask you questions 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 weak design. we all know devices (esp. electronics) that come with huge manuals and complicated explanations - bummer.

in this respect, your API is the same as any other consumer device. it should be "well afforded." developers should not have to read the technical equivalent of Tolstoy's "War and Peace" before they can 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 are helpful for devs, but they can be daunting to read and cumbersome to maintain.

another approach is the include this kind of information in a machine-readable format. one that most devs will also understand quickly. a set of instructions that get automatically updated whenever your API changes - 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) in your API responses?

help your client devs out. throw 'em a bone, here. don't make them read pages of docs when you can just include the simple run-time instructions instead.

in conclusion

if they have to ask, you didn't afford it.

Hypermedia