Step 2: Endpoints and methods (API reference tutorial)

Endpoints and methods: The endpoints indicate how you access the resource, and the method used with the endpoint indicates the allowed interactions (such as GET, POST, or DELETE) with the resource. The endpoint shows the end path of a resource URL only, not the base path common to all endpoints. The same resource usually has a variety of related endpoints, each with different paths and methods but returning variant information about the same resource. Endpoints usually have brief descriptions similar to the overall resource description but shorter.

Example of an endpoints

Here’s an example of the endpoints for the Relationships resource in the Instagram API:

The endpoint is usually set off in a stylized way that gives it more visual attention. Much of the documentation is built around the endpoint, so it might make sense to give each endpoint more visual weight in your documentation.

The endpoint is arguably the most important aspect of API documentation, since this is what developers will implement to make their requests.

Represent path parameters with curly braces

If you have path parameters in your endpoint, represent them through curly braces. For example, here’s an example from Mailchimp’s API:

/campaigns/{campaign_id}/actions/send

Better yet, put the path parameter in another color to set it off:

/campaigns/{campaign_id}/actions/send

Curly braces are a convention that users will understand. In the above example, almost no endpoint uses curly braces in the actual path syntax, so the {campaign_id} is an obvious placeholder.

Here’s an example from the Facebook API that colors the path parameter in an easily identifiable way:

When the parameters are described, the same green color is used to set off the parameters, which helps users recognize their meaning.

Path parameters aren’t always set off with a unique color (for example, some precede it with a colon), but whatever the convention, make sure the path parameter is easily identifiable.

You can list the method beside the endpoint

It’s common to list the method (GET, POST, and so on) next to the endpoint. The method defines the operation with the resource. Briefly, each method is as follows:

  • GET: Retrieve a resource
  • POST: Create a resource
  • PUT: Update or create within an existing resource
  • PATCH: Partially modify an existing resource
  • DELETE: Remove the resource

See Request methods in Wikipedia’s article on HTTP for more details. (There are some additional methods, but they’re rarely used.)

Since there’s not much to say about the method itself, it makes sense to group the method with the endpoint. Here’s an example from Box’s API:

Box API

And here’s an example from Linkedin’s API:

Linkedin Example

Sometimes the method is referred to as the “verb.” GET, PUT, POST, PATCH, and DELETE are all verbs or actions.

The endpoint shows the end path only

When you describe the endpoint, you list the end path only (hence the term “end point”). The full path that contains both the base path and the endpoint is often called a resource URL.

In our sample API scenario, the endpoint is just /surfreport/{beachId}. You don’t have to list the full resource URL every time (which would be https://simple-weather.p.mashape.com/surfreport{beachId}). Including the full resource URL would distract users from focusing on the path that matters. In your user guide, you usually explain the full resource URL, along with the required authorization, in an introductory section.

How to group multiple endpoints for the same resource

Another consideration is how to group and list the endpoints, particularly if you have a lot of endpoints for the same resource. In the resource descriptions step, we looked at a variety of APIs, and many provide different document designs for grouping or listing each endpoint for the resource. So I won’t revisit all the same examples. Group the endpoints in some way that makes sense, such as by method or by the type of information returned.

For example, suppose you had three GET endpoints and one POST endpoint, all of which are related to the same resource. Some doc sites might list all the endpoints for the same resource on the same page. Others might break them out into separate pages. Others might create one group for the GET endpoints and another for the POST endpoints. It depends how much you have to say about each endpoint.

If the endpoints are mostly the same, consolidating them on a single page could make sense. But if they’re pretty unique (with different responses, parameters, and error messages), separating them out onto different pages is probably better (and easier to manage). Then again, with a more sophisticated website design, you can make lengthy information navigable on the same page.

In a later section on design patterns, I explore how long pages are common pattern with developer docs, in part because they make content easily findable for developers using Ctrl + F.

How to refer to endpoints

How do you refer to the endpoints within an API reference topic? Referring to the “/aqi endpoint” or to the “/weatherdata” endpoint doesn’t make a huge difference. But with more complex APIs, using the endpoint to talk about the resource can get problematic.

At one company I worked at, our URLs for the Rewards endpoints looked like this:

// get all rewards
/rewards

// get a specific reward
/rewards/{rewardId}

// get all rewards for a specific user
/users/{userId}/rewards

// get a specific reward for a specific user
/users/{userId}/rewards/{rewardId}

And rewards in context of Missions looked like this:

// get the rewards for a specific mission related to a specific user
/users/{userId}/rewards/{missionId}

// get the rewards available for a specific mission
/missions/{missionid}/rewards

To say that you could use the rewards resource wasn’t always specific enough, because there were multiple rewards and missions endpoints.

It can get awkward referring to the endpoint. For example, “When you call /users/{userId}/rewards/, you get a list of all rewards. To get a specific reward for a specific mission for a specific user, the /users/{userId}/rewards/{missionId} endpoint takes several parameters…” The longer the endpoint, the more difficult the reference. These kinds of descriptions are more common in the non-reference sections sections of your documentation. However, brief and clear references to the endpoints are sometimes challenging.

Endpoint for surfreport API

Let’s create the Endpoints section for our fictitious surfrefport API. Here’s my approach:

Endpoints

GET surfreport/{beachId}

Gets the surf conditions for a specific beach ID.

(There’s not much to see here – endpoints look best when styled attractively with CSS.)

Next steps

Now that we’ve described the resource and listed the endpoints and methods, it’s time to tackle one of the most important parts of an API reference topic: the parameters section.

21% Complete

21/91 pages complete. Only 70 more pages to go...

Get new posts delivered straight to your inbox.

Subscriber count: 4,285