1. I'd Rather Be Writing
2. Docs
3. Chapter 3: Documenting API endpoints

Step 1: Resource description (API reference tutorial)

Download PDF

• Examples of resource descriptions
• Terminology for describing the resource
• Recognize the difference between reference docs versus user guides
• Resource description for the surfreport endpoint
• Next steps

Examples of resource descriptions

Here’s an example of a resource description from the Mailchimp API’s Campaigns resource:

Typically, an API will have a number of endpoints grouped under the same resource. In this case, you describe both the general resource and the individual endpoints. For example, the Campaigns resource has various endpoints that are also described:

• POST /campaigns
• GET /campaigns
• GET /campaigns/{campaign_id}
• PATCH /campaigns/{campaign_id}
• DELETE /campaigns/{campaign_id}
• POST /campaigns/{campaign_id}/actions/cancel-send
• POST /campaigns/{campaign_id}/actions/pause
• POST /campaigns/{campaign_id}/actions/replicate
• POST /campaigns/{campaign_id}/actions/resume
• POST /campaigns/{campaign_id}/actions/schedule
• POST /campaigns/{campaign_id}/actions/send
• POST /campaigns/{campaign_id}/actions/test
• POST /campaigns/{campaign_id}/actions/unschedule

Here’s a resource description for the Membership resource in the Box API:

For the Membership resource (or “object,” as they call it), there are 7 different endpoints or methods you can call. The Box API describes the Membership resource and each of the endpoints that lets you access the resource.

Sometimes the general resource isn’t described; instead, it just groups the endpoints. The bulk of the description appears in each endpoint. For example, in the Eventbrite API, here’s the Events resource:

Although the Events resource isn’t described here, descriptions are added for each of the Events endpoints. The Events resource contains all of these endpoints:

• /events/search/
• /events/
• /events/:id/
• /events/:id/
• /events/:id/publish/
• /events/:id/cancel/
• /events/:id/
• /events/:id/display_settings/
• /events/:id/display_settings/
• /events/:id/ticket_classes/
• /events/:id/ticket_classes/:ticket_class_id/
• /events/:id/canned_questions/
• /events/:id/questions/
• /events/:id/attendees/
• /events/:id/discounts

And so on.

When developers create APIs, they have a design question to consider: Use many variants of endpoints (as with Eventbrite’s API), or provide lots of parameters to configure the same endpoint. Often there’s a balance between the two. The trend seems to be toward providing separate endpoints rather than supplying a host of potentially confusing parameters within the same endpoint. On the other hand, GraphQL APIs (which I don’t cover in this course) provide one endpoint with different ways to query the information the endpoint contains. See GraphQL And REST Differences Explained With Burgers for a good explanation about GraphQL versus REST.

As another example, the previous version of the Instagram API depicted a Relationships resource as follows:

The Relationships resource isn’t described but rather acts as a container for relationship endpoints. Descriptions are added for each of the resources grouped within the Relationships resource:

• GET /users/self/followsGet
• GET /users/self/followed-byGet
• GET /users/self/requested-byList
• GET /users/user-id/relationshipGet
• POST /users/user-id/relationshipModify

(Instagram has since shifted to a Graph API.)

For another example of an API with resources and endpoints, check out the Trello API.

The description of the resource is likely something you’ll re-use in different places — product overviews, tutorials, code samples, quick references, etc. As a result, put a lot of effort into crafting it. Consider storing the description in a re-usable snippet in your authoring tool so that you can list it without resorting to copy/paste methods in your quick start guide.

Terminology for describing the resource

The exact terminology for referring to resources varies. The “things” that you access using a URL can be referred to in a variety of ways, but “resource” is the most common term because you access them through a URL, or uniform resource locator. Other than “resources,” you might see terms such as API calls, endpoints, API methods, calls, objects, services, and requests. Some docs get around the situation by not calling them anything explicitly except “Reference.”

Despite the variety with terminology, generally an API has various “resources” that you access through “endpoints.” The endpoints give you access to the resource. (But terminology isn’t standard, so expect variety.)

For more on how API terminology varies, see The difference between resources, endpoints, objects, and items in the bunq API documentation.

Recognize the difference between reference docs versus user guides

Resource descriptions (as well as endpoint descriptions) are typically short, usually 1-3 sentences. What if you have a lot more detail to add? In these situations, keep in mind the difference between reference documentation and user guides/tutorials:

• Reference documentation: Concise, bare-bones information that developers can quickly reference.
• User guides/tutorials: More elaborate detail about how to use the API, including step-by-step instructions, code samples, concepts, and procedures. I go into much more detail about this content in Documenting concepts sections.

Although the description in an API reference topic provides a 1-3 sentence summary of the information that the resource contains, you might expand on this with much greater detail in the user guide. (You could link the reference description to the places in the guide where you provide more detail.)

Resource description for the surfreport endpoint

Let’s review the surf report wiki page (which contains the information about the resource) and try to describe the resource in 1-3 sentences. Here’s my approach:

Next steps

Now it’s time to list out the endpoints and methods for the resource.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.