Search results

Inspect the JSON from the response payload

Seeing the response from curl or Postman is cool, but how do you make use of the JSON data? With most API documentation, you don’t need to show how to make use of JSON data. You assume that developers will use their front-end development skills to parse through the data and display it appropriately in their apps. However, to better understand how developers will access the data, we’ll go through a brief tutorial to display the REST response on a web page.

RAML tutorial

RAML stands for REST API Modeling Language and is similar to the OpenAPI specification. RAML is backed by Mulesoft, a full-service, end-to-end API company.

Putting it all together

Let’s pull together the various parts we’ve worked on and bring them together to showcase the full example.

How much code do you need to know?

With developer documentation roles, some level of coding is required. But you don’t need to know as much as developers, and acquiring that deep technical knowledge will usually cost you expertise in other areas.

Scenario for using a weather API

Let’s start using an actual REST API to get more familiar with how they work. In the upcoming sections, you’ll explore some weather APIs in the context of a specific use case: retrieving a weather forecast. By first playing the role of a developer using an API, you’ll gain a greater understanding of how your audience will use APIs, the type of information they’ll need, and what they might do with the information.

Documenting APIs: A guide for technical writers and engineers

In this course on writing documentation for APIs, instead of just talking about abstract concepts, I contextualize 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.

Activity: Complete the SendGrid Getting Started tutorial

In this section, you explored Getting started tutorials. To get better empathy for these tutorials as a user, try to complete the following tutorial from SendGrid: Getting Started with the SendGrid API.

API best practices

API best practices can refer to any general advice your product team wants to communicate to developers about working with the API. There aren’t any set number of topics typically covered in API best practices. Instead, the best practices can be a catch-all title for content that doesn’t fit anywhere else.

Step 4: Request example (API reference tutorial)

The request example includes a sample request using the endpoint, showing some parameters configured. The request example usually doesn’t show all possible parameter configurations, but it should be as rich as possible with parameters. Sample requests sometimes include code snippets that show the same request in a variety of languages (besides curl). Requests shown in other programming languages are optional and not always included in the reference topics (but when available, users welcome them).

What's new

If you’re looking to see what’s new in the API doc site/course, you can browse new content in several ways.

Activity: Create an OpenAPI specification document

The OpenAPI tutorial walked you through 8 steps in building the OpenAPI specification document. Now it’s your turn to practice first editing and then creating an OpenAPI specification document.

Step 7: The tags object (OpenAPI tutorial)

The tags object allows you to arrange the paths (endpoints) into named groups in the Swagger UI display.

Understand curl more

Almost every API shows how to interact with the API using curl. So before moving on, let’s pause a bit and learn more about curl.

Survey of API doc sites

Rather than approach the topic of publishing prescriptively, let’s begin with some concrete examples and move towards the formulation of general principles. The following are more than 100 openly accessible REST APIs that you can browse as a way to look at patterns and examples.

More REST API activities

To get more practice working with various APIs, I provide several examples in this Resources section. Working through these activities will give you more exposure to different REST APIs, how they’re organized, the complexities and interdependency of endpoints, and more.

Contact me

Feel free to ask me any questions you like. It might take me a few days to respond. You can contact me directly using the form below:

HTML Forms powered by Wufoo.

Buy me a coffee

This domain is not registered with Commento.