Introduction:  I re-joined Oracle as a technical writer and content strategist in a storage systems development group over two years ago. In mid-2017, our team recognized the need to expand our content about a system’s evolving REST API. Like many veterans of hardware documentation, I didn’t know much about APIs, RESTful or otherwise. So I embarked on a journey to learn more.

This blog, written originally near the beginning of that journey (for a class) and updated since, presents helpful links and guidelines about REST APIs for former hardware technical writers like me.

Technology services based on the representational state transfer (REST) architecture or a RESTful application programming interface (API) are becoming more important for hardware developers and content developers to understand. Wait, what? Why do I have to understand programming stuff?

Well, I hate to break it to you, but programming isn’t just for coders any more. APIs in general – and REST APIs in particular – play an increasingly central role in the burgeoning cloud services market as well as the Internet of Things (IoT), according to Jennifer Riggins and others.

Because APIs provide a “level of abstraction” beyond the uniqueness of the “thing” itself, they enable a connectedness and interconnectedness that we mere humans have not seen from our refrigerators and vacuums before. For a perspective, review Alexandra Bowen’s still-relevant 2016 SlideShare set, and memorize her first answer to the question – Why APIs? “APIs provide the ability to glue and integrate services.”

REST API Concepts

Before you start to panic, remember that a REST API is based on the target’s “resources” – that is, the elements of the hardware itself as well as the data that journeys to and from that hardware:  disk drives, temperature sensors, network connections, user account data, and so on. These are concepts most of you are already familiar with.

Also remember that actual “programming” doesn’t really occur within the REST architecture. Activity is limited to configuring, retrieving, changing, or removing the target’s resources. These activities are controlled by the four main HTTP methods – GET, POST, PUT, and DELETE – which are common across most REST APIs. (For a description of the HTTP methods, refer to the RestAPITutorial page on the topic.)

If you need to get further acquainted or re-acquainted with REST concepts and terminology, review the Pearson eCollege tutorial on YouTube. And yes, for those of you who love Wikipedia, it offers a pretty good overview, too.

Guidelines for Documentation

Development of REST API content has become more standardized in recent years. Writers can assume a certain amount of experience and knowledge on the part of the audience, especially developers. Consumers of REST API documentation, in turn, expect to see content that meets them at their level. They may even expect the content to be organized in a certain manner or contain certain topics.

So as with any documentation project, start with understanding the REST API’s audience. To gather some tips about audiences, read Diana Lakatos’ blog “The Ten Essentials for Good API Documentation.”

Next, use the following eight guidelines to plan and organize your REST API content:

1. Create a short Getting Started section that contains the following:
   1. The format for a fully qualified URI, including the base URL
   2. Authentication instructions
2. Describe any unique request headers or unique use of request headers, or anything else unique about the API, including special query parameters.
3. Include an alphabetical list of resources for easy reference.
4. Provide details about each resource and endpoint; if need be, group the resources into logical categories for better management of the details.
5. Provide lots of example requests and, as needed, example responses. Developers love code examples!
6. Ensure that all your code examples appear in the programming language most often used by the target audience (for example, JSON).
7. Include a list of status (HTTP) codes.
8. Provide guidance for error-handling, as needed.

Going Further with REST API Documentation

For more tips on how best to document a REST API, review the 2016 SlideShare set from Marta Rauch of Oracle Corporation and read Diana Lakatos’ second blog “Ten Extras for Great API Documentation.”

Many RESTful API gurus point to Twilio’s REST API guide as a model for good API content. However, I prefer Twitter’s approach, which I find easier to navigate. For an example of hardware-specific documentation, see Oracle’s guide to the RESTful API for its ZFS Storage Appliance (written by a team other than mine).

Finally, as for which tools to use when you document your product’s REST API, almost any good documentation tool will suffice. That said, there is a growing trend among professionals to intertwine REST API development and documentation by using tools like Swagger – now associated with the OpenAPI Specification or OAS (refer to http://swagger.io/).

For some tips on how to evaluate REST API documentation tools, read the Algolia blog “Good API Documentation Is Not about Choosing the Right Tool.” For a review of available tools, read the article “Best Practices and Tools for Documenting APIs” by Mark Boyd of ProgrammableWeb, a news and information website dedicated to APIs.

Now you know as much or more than I did when I started my journey. Good luck to you!

Note: Mention of products or companies in this blog does not constitute an endorsement of those products or companies by me.