Search results

Next phase of course

Congratulations, you finished the documenting REST APIs section of the course. You’ve learned about the core elements in REST API documentation. We haven’t covered publishing tools or strategies yet. Instead, this part of the course has focused on the creating content, which should always be the first consideration.

Summary of what you learned

During this part of the course, you learned the core tasks involved in documenting REST APIs. First, as a developer, you learned the following:

  • How to make calls to an API using curl and Postman
  • How to pass parameters to API calls
  • How to inspect the objects in the JSON payload
  • How to use dot notation to access the JSON values you want
  • How to integrate the response into a web page

Then you switched perspectives and approached APIs from a technical writer’s point of view. As a technical writer, you documented each of the main components of a REST API:

  • Resource description
  • Endpoints and methods
  • Parameters
  • Request example
  • Response example and schema

Although the technology landscape is broad, and there are many different technology platforms, languages, and code bases, most REST APIs have these same sections in common.

After working through the reference documentation, you focused on the user guide (or non-reference) topics in documentation. You examined the following topics in the context of actual API doc sites:

  • API overview
  • Getting started tutorials
  • Authentication and authorization
  • Status and error codes
  • SDKs and sample apps
  • Quick reference guides
  • Code samples and tutorials, and more

The next part of the course

Now that you’ve got the content down, let’s look at some standard specifications that have been developed for much of this same information (well, at least for the reference information). In the next section, we’ll dive into the OpenAPI specification and Swagger.

52% Complete

52/109 pages complete. Only 57 more pages to go...


Would you like to help encourage more content development and updates? If so, click the Donate button below to donate $10 through Paypal.

Get new posts delivered straight to your inbox.

Subscriber count: 4,285