If They Have to Ask, You Didn't Afford It

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.)

The Author

Mike Amundsen

Lead API Architect

An internationally-known author and lecturer, Mike Amundsen travels throughout the United States and Europe, consulting and speaking on a wide range of topics including distributed network architecture, Web application development and cloud computing. His recent work focuses on the role hypermedia plays in creating and maintaining applications that can successfully evolve over time. He has more than a dozen books to his credit, the most recent of which is RESTful Web APIs.

Related Articles

Microservices

Applying and Extending DHARMA

This post gives some practical examples of the DHARMA method for API Security in a Microservice Architecture, and also shares some opportunities for extending the model.

Matt McLarty on Jul 9, 2018

Microservices and APIs
API Strategy

Microservices, APIs and Innovation: The Power of APIs

Explore the role APIs play in empowering teams and enabling organizations to innovate.

Mike Amundsen on May 24, 2018

How API Languages Evolve
API Design

How API Languages Evolve

As API systems mature, knowing the history and evolution of various API languages will help organizations create robust and successful landscapes.

Erik Wilde on Oct 17, 2017

Join the Conversation