January 16, 2023

Getting Started in API Documentation

Posted in Career, Documentation, Information Architecture, technology tagged , , , , , at 1:13 pm by degyes

In the spirit of celebrating the new calendar year, I’m sharing with you and the group some insights I’ve gleaned on helping new API docs writers get launched.
I’d recommend visiting GitHub and checking out the location for newbies interested in doing practice projects. Here are the public APIs in GitHub:

https://github.com/public-apis/public-apis. (There might be a newer site that addresses some ownership controversies that had apparently taken place last summer: https://apislist.com/.)

Here’s a sample of an openly available API that seems fairly rich, i.e., contains some actual content that could be applied in real life: https://fiscaldata.treasury.gov/api-documentation/.

I’d also highly recommend checking out Swagger and Postman. Start out with the open-source stuff (they may have some sandboxed areas where you can practice).

To place some context around all this, the idea is to first get a sense of the overall structure, starting from the top-level API branches, then listing all the API endpoints (i.e., call functions) belonging to each branch. You then break down each endpoint, detailing:

  • Syntax – where the API endpoint resides in the structure
  • Description / purpose – you make this up
  • Request URL – basically the syntax expressed as a URL, i.e., http:// …
  • HTTP Method, i.e., GET, POST, PUT, DELETE, etc.
  • URL Path Parameters – a more detailed breakdown of the parameters that need to (or can optionally) be defined to enable requesting info from the API. This is sometimes written as a table with the following columns: Field / Type / Description, although lately I’ve seen this handled in a more minimalist way.
  • Response Body – an example containing the JSON code that’s returned when a properly syntactically written function call is made to the API. This can be anywhere from a little to a lot of JSON code. There are tools that can help you parse “raw” code into nicely formatted, readable code. (I’ve used this one … https://codebeautify.org/jsonviewer).

Of course, how _you_ document the above is a function of the nature of the particular API, the needs and expectations of your readership (as well as the developers), and your own technical creativity and sense of design.

For instance, one of the things found missing in lots of otherwise well-documented (and pretty) APIs is concrete, real-life, practical examples. That is, how a given API is to be implemented in practice. Lesson: a key differentiator that makes an API doc truly excellent is taking it beyond just covering otherwise disembodied code.

For a great example of the above, check out the API tutorials that Google provides for its well-known mapping functions. https://developers.google.com/maps/documentation/javascript/tutorials

In closing, for the sake of sheer elegance and sense of “wow!” here is a very short list of APIs that have accrued a fan following among the API docs community.

I hope that you and the techshoret community find this helpful.

Expressing my personal hopes and prayers that 2023 be healthy, peaceful, prosperous and successful for us all.
-Dave Egyes

N.B. – Here is a basic level primer that explains the basics of REST APIs, providing a nice overview of the fundamentals needed to get started: REST APIs: How They Work and What You Need to Know.