Search results

Documenting APIs: A guide for technical writers

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

In this course on writing documentation for REST APIs, instead of just talking about abstract concepts, I contextualize REST APIs with a direct, hands-on approach. You’ll first learn about API documentation by using a simple weather API to put a weather forecast on your site.

As you use the API, you’ll learn about endpoints, parameters, data types, authentication, curl, JSON, the command line, Chrome’s Developer Console, JavaScript, and more. The idea is that rather than learning about these concepts independent of any context, you learn them by immersing yourself in a real scenario while using an API. This makes these tools and technologies more meaningful.

We’ll then transition into standards, tools, and specifications for REST APIs. You’ll learn about the required sections in API documentation, analyze examples of REST API documentation from various companies, learn how to join an open-source project to get experience, and more.

About REST APIs

In a nutshell, REST APIs (which are a type of web API) involve requests and responses, not too unlike visiting a web page. You make a request to a resource stored on a server, and the server responds with the requested information. The protocol used to transport the data is HTTP. “REST” stands for representational state transfer.

Response and request model for REST APIs
REST APIs involve requests and responses over HTTP protocol

I dive more into the principles of REST in What is a REST API? In your REST API documentation, you describe the various endpoints available, their methods, parameters, and other details, and you also document sample responses from the endpoints.

From practice to documentation

In this course, after you practice using an API like a developer, you’ll then shift perspectives and “become a technical writer” tasked with documenting a new endpoint that has been added to an API.

As a technical writer, you’ll tackle each element of a reference topic in REST API documentation:

  1. Resource descriptions
  2. Endpoints and methods
  3. Parameters
  4. Request example
  5. Response example

Diving into these sections will give you a solid understanding about how to document REST APIs. You’ll also learn how to document the non-reference sections for an API, such as the getting started, status and error codes, request authorization, and more.

Finally, you’ll dive into different ways to publish REST API documentation, exploring tools and specifications such as GitHub, Jekyll, and other docs-as-code approaches. You’ll learn how to leverage templates, build interactive API consoles so users can try out requests and see responses, and learn how to manage your content through version control.

We’ll also dive into specifications such as the OpenAPI specification and Swagger, which provides tooling for the OpenAPI specification. Additionally, you’ll learn how to document native library APIs and generate Javadoc. Throughout this course, I put these concepts in real, applicable contexts with examples and demos.

Course organization

This course is organized into the following sections:

  • I: Introduction to REST APIs: REST APIs are flourishing in the marketplace, and the web is becoming a mashup of interconnected APIs. REST APIs consist of requests to and responses from a web server. Job prospects are hot for technical writers who can write developer documentation. This course will help you break into API documentation, especially if you complete the many hands-on activities.

  • II: Using an API like a developer: Playing a brief role as a developer will help you understand what’s important in API documentation. Developers often use tools such as Postman to make calls. They look at the structure of the response. And they pull out the needed information to integrate them into web pages and other applications.

  • III: API endpoints: Reference documentation for API endpoints conforms to five general sections: resource descriptions, endpoints and methods, parameters, sample requests, sample responses and schemas. When you document an API, provide detailed information for each of these reference sections.

  • IV: OpenAPI spec and Swagger: The OpenAPI specification provides a formal way of describing your REST API, and includes all the reference sections mentioned in Documenting API endpoints. Display frameworks such as Swagger UI can parse the OpenAPI specification and generate interactive documentation that lets users try out endpoints while learning about the API.

  • V: Testing API docs: Testing your documentation is critical to providing accurate, thorough information. With API and developer docs, due to the high level of complexity and engineering requirements, technical writers might be inclined to simply take information that engineers give them and incorporate them wholesale, without personally testing them. This can reduce your role to being an engineer’s secretary.

  • VI: Non-reference API topics: While reference topics in API generally receive the most attention, the non-reference topics, such as getting started tutorials, information about authorization, rate limiting, status and error codes, quick reference guides, and more constitute about half the documentation. These topics are usually handled more by technical writers than engineers. You can evaluate documentation by looking to see whether it includes these non-reference topics.

  • VII: Publishing API docs: API documentation often follows a docs-as-code workflow, where the tools to author and publish documentation align closely with the same tools developer use to write code. This involves using lightweight formats such as Markdown, collaborating with Git or other version control, building your doc site with a static site generator, and deploying it through a continuous build model, where the build happens on the server when you push commits to a particular branch.

  • VIII: Getting a job in API doc: Getting a job in API documentation requires you to demonstrate your techncial aptitude through a writing portfolio. The portfolio should include samples of documentation written for developers. One way to build this portfolio by working on an open-source project. Overall, thriving in the developer documentation space requires you to continually learn a healthy dose of code, which can be challenging.

  • IX: Native library APIs: Native library APIs refer to Java, C++, or other programming-specific APIs. In this model, rather than making requests across the web for the information, you download a library of code an integrate it into your project. The library is compiled into your application’s build. Although this type of API is less common, I include it here in part to clarify what makes REST (or web) APIs so different.

  • X: API glossary and resources: The API documentation landscape is full of jargon, acronyms, and many new terms. This glossary provides a list of terms and definitions. Additionally, this section contains additional exercises and information, such as more activities calling APIs, or more info about alternative specifications.

You don’t have to read the sections in order — feel free to skip around as you prefer. But some of the earlier sections (such as the section on Using a REST API like a developer and Documenting endpoints) follow a somewhat sequential order with the same weather API scenario.

Because the purpose of the course is to help you learn, there are many activities that require hands-on coding and other exercises. Along with the learning activities, there are also conceptual deep dives, but the focus is always on learning by doing. Where there are hands-on activities, I typically include this icon in the section title: .

Other topics have the word “Activity” in the title. The activities are integrated in various sections, but you can also see a consolidated list of activity content in the Workshop Activities.

I refer to the content here as a “course” instead of a book or a website, primarily because I include a lot of exercises throughout in each section, and I find that people who want to learn API documentation prefer a more hands-on “course” experience.

Will this course help you get a job in API documentation?

The most common reason people take this course is to transition into API documentation. This course will help you make that transition, but you can’t just passively read through the content. You need to do the activities outlined in each section, especially those topics that involve working with content from an open-source project. These activities are key to building experience and credibility with a portfolio. I provide more details in Getting a job in API documentation.

No programming skills required

As for the needed technical background for the course, you don’t need any programming background or other prerequisites, but it will help to know some basic HTML, CSS, and JavaScript.

If you do have some familiarity with programming concepts, you might speed through some of the sections and jump ahead to the topics you want to learn more about. This course assumes you’re a beginner, though.

Some of the code samples in this course use JavaScript. JavaScript may or may not be a language that you actually use when you document REST APIs, but most likely there will be some programming language or platform that becomes important to know.

JavaScript is one of the most useful and easy languages to become familiar with, so it works well in code samples for this introduction to REST API documentation. JavaScript allows you to test out code by merely opening it in your browser (rather than compiling it in an IDE). (I have a quick crash-course in JavaScript here if you need it.)

What you’ll need

Here are a few tools you’ll need to do the exercises in this course:

  • Text editor. (Atom editor or Sublime Text are good options, and they work on both Mac and Windows.)
  • Chrome browser. Chrome provides a Javascript Console that works well for inspecting JSON, so we’ll be using Chrome. Firefox works well too if you prefer that.
  • Postman. Postman is an app that allows you to make requests and see responses through a GUI client.
  • curl. curl is essential for making requests to endpoints from the command line. Mac computers already have curl installed. Windows users should follow the instructions for installing curl here. (Note: Choose one of the “free” versions to install curl.)
  • Git. Git is a version control tool developers often use to collaborate on code. For Windows, see https://gitforwindows.org/ to set up Git and the Git BASH terminal emulator. For Mac, see Downloading Git and also consider installing iTerm2.
  • GitHub account. GitHub will be used for various activities and is commonly used as an authentication service for developer tools. If you don’t already have a GitHub account, sign up for one.
  • Stoplight account. Stoplight provides visual modeling tools for working with the OpenAPI specification. Create a Stoplight account using your GitHub credentials. (You don’t need the app.)
  • OpenWeatherMap API key. We’ll be using the OpenWeatherMap API for some exercises. It takes a couple of hours for the OpenWeatherMap API key to activate, so it’s best if you get the API key ahead of time — then when you get to the OpenWeatherMap API activities, you’ll be all set. To get your (free) OpenWeatherMap API key, go to https://openweathermap.org/. Click Sign Up in the top nav bar and create an account. After you sign up, sign in and find your default API key from the developer dashboard. It’s under the API Keys tab. Copy the key into a place you can easily find it.

Video recordings

For video recordings of this course, see the Recorded Video Presentations. The most recent full-length video of the entire course is a full-day API workshop I gave in Menlo Park, California, in November 2018. The video doesn’t go into the same level of detail as the written material, but it would be a good start.

See my Upcoming Presentations on my blog for details about future workshops and presentations.

Course slides

For the live workshops, I have various slides that cover different sections of this course. If you’re a teacher adapting this material for a course on API documentation in a tech comm program, you can clone and modify the slides. See Course Slides for the links. Basically, you would clone this GitHub repo and copy over the content from the slides directory.

The slides use RevealJS, which is an HTML/CSS/JS framework for slides. The images are single-sourced between the site and the slides, so they’ll more likely stay in sync. You can adapt the slides as needed for your lessons.

Let me know if any content is out of date

One of the challenges in any technical course is ensuring the content stays up to date. Technology changes rapidly, and given the many hands-on activities in the course, it’s easy for some steps to become out of date as time passes. I’ve tried to maintain a healthy balance between general and specific details in the content here. If you find something is out of date, either add a comment on that page or let me know.

Stay updated

If you’re following this course, you most likely want to learn more about APIs. I publish regular articles that talk about APIs and strategies for documenting them. You can stay updated about these posts by subscribing to my free newsletter.

3% Complete

3/110 pages complete. Only 107 more pages to go...

Donate?

Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.