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
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.
This method takes a postcode and returns the associated address.
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.
This 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:
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.