Step 1: Resource description (API reference tutorial)

Resource description: "Resources" refers to the information returned by an API. Most APIs have various categories of information, or various resources, that can be returned. The resource description provides details about the information returned in each resource. The resource description is brief (1-3 sentences) and usually starts with a verb. Resources usually have a number of endpoints to access the resource, and multiple methods for each endpoint. Thus, on the same page, you usually have a general resource described along with a number of endpoints for accessing the resource, also described.

Example of a resource description

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. Normally, 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:

Example from Box

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 let 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 a lot of 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 with the same endpoint.

As another example, here’s the Relationships resource in the Instagram API.

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

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.

Despite the variety with terminology, in general 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.) The Mashape Weather API is pretty simple, and just refers to 3 “endpoints” available.

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.

Although the description in an API reference topic provides a 1-3 sentence summary of the information 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

Activity

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:

Surfreport

Contains information about surfing conditions, including the surf height, water temperature, wind, and tide. Also provides an overall recommendation about whether to go surfing.

Next steps

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

20% Complete

20/91 pages complete. Only 71 more pages to go...

Get new posts delivered straight to your inbox.

Subscriber count: 4,285