1. apidoc
2. documenting APIs
3. Documenting API endpoints

Step 2: Endpoints and methods (API reference tutorial)

The endpoints indicate how you access the resource, while the method indicates the allowed interactions (such as GET, POST, or DELETE) with the resource.

The same resource usually has a variety of related endpoints, each with different paths and methods but returning different information about the same resource. Endpoints usually have brief descriptions similar to the overall resource description but shorter. Also, the endpoint shows the end path of a resource URL only, not the base path common to all endpoints.

• Examples of endpoints
• Represent path parameters with curly braces
• You can list the method next to the endpoint
• The endpoint shows the end path only
• How to group multiple endpoints for the same resource
• How to refer to endpoints in tutorials
• Endpoint for surfreport API
• Next steps

Examples of 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 because 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

If you can, put the path parameter in another color to set it off:

/campaigns/{campaign_id}/actions/send

Curly braces for path parameters 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 in Facebook’s docs, 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 next to 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: Retrieves a resource
• POST: Creates a resource
• PUT: Updates or creates within an existing resource
• PATCH: Partially modifies an existing resource
• DELETE: Removes 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 the Box API:

And here’s an example from the Linkedin API:

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://api.openweathermap.org/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 (such as the Getting started tutorial).

How to group multiple endpoints for the same resource

Another consideration in documenting endpoints and methods is how to group and list the endpoints, particularly if you have a lot of endpoints for the same resource. In Examples of resource descriptions, we looked at a variety of APIs. Many doc sites provide different 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 have three GET endpoints and one POST endpoint, all of which relate to the same resource. Some doc sites might list all the endpoints for the same resource on the same page. Others might break them 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 substantially unique (with different responses, parameters, and error messages), separating them 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 explain that 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 in tutorials

In tutorials and other conceptual content, 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 be tricky.

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

/rewards

/rewards/{rewardId}

/users/{userId}/rewards

/users/{userId}/rewards/{rewardId}

And rewards in context of Missions looked like this:

/users/{userId}/rewards/{missionId}

/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, you might have a sentence like this: “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 cumbersome the reference becomes. These kinds of descriptions are more common in the conceptual sections of your documentation. Generally, there’s not a clear convention about how to refer to cumbersome endpoints. Adopt an approach that makes the most sense for your API.

Endpoint for surfreport API

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

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.