Your API sucks : documentation

Your API is perfect. It just needs a little finesse on the documentation. It’s fine, just farm it out to Johnny Clueless. After all, good APIs, like all good code, is self documenting. It’s just those damn users that keep asking what you mean when you said that, or wanting to know what all the options are. They’re very demanding.

Documentation out of sync with the code

getPostcode(double opt)
This method takes returns the current longitude and latitude of the user based on the information provided by their device.

Teaching Granny to suck eggs

Bad API documentation is like bad comments, it tells you everything except what you need to know, such as the return format.

getAddressFromPostcode(string postcode)
This method takes a postcode and returns the associated address.

Be explicit

However, don’t use this as an excuse to avoid documentation. Good documentation helps users access your API without using up your time. Be explicit about options, about which standards you support, and where necessary, how you support them. Even for simple things.

explicit-documentationThis image represents an authentication call to retrieve an API token that can be used when making further calls to an API. Each of the arrows represents an email discussion where the user needed clarification. This can be simplified with the right explicit statement:

To retrieve your API token, a POST request must be made to the HTTPS URL provided, with the following key-value pairs x-www-form-urlencoded into the Body of the request:

Key                       Value

client_id              your_username

client_secret      your_password

grant_type          client_credentials

If successful, this will return a JSON body in the response. The value associated with the key access_token should be appended to all subsequent requests as described below.

The use of italics is defined appropriately, and user specific information is supplied in a format to match the documented table.

Advertisements

2 thoughts on “Your API sucks : documentation

  1. Documentation is important and is one of the 8 key values identified in the Agile Manifesto!

    Effective documentation is much more important than Copious quantities, however.

    The example above of “Bad API documentation is like bad comments, it tells you everything except what you need to know, such as the return format.”….

    The return format is indeed important information, but is the one and only place it is needed? Doubtful. Therefore a link to the information may be much more effective than having it directly here (and in all of the other places).

    Even with the ‘boiler plate” type, there can be value. For example if the in-situ documentation [XML Comments, DoxyGen, etc.] is being processed into a comprehensive environment [e.g. SandCastle] then the boiler plate may be all that is needed for various tables and other elements [either inline our out of band] could supply the details.

    Also don’t forget that EVERY test for a piece of code is also a documentation element!!!!

    Liked by 1 person

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s