Search results

Step 2: Endpoints and methods (API reference tutorial)

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

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 different information about the same resource. Endpoints usually have brief descriptions similar to the overall resource description but shorter.

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


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


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 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 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: 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 Box’s 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{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 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 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 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 substantially 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 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 non-reference 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 get problematic.

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





And rewards in context of Missions looked like this:



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 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. There’s not a clear solution about how to refer to cumbersome endpoints. Adopt a convention that makes the most sense for your API.

Endpoint for surfreport API

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


GET surfreport/{beachId}

Gets the surf conditions for a specific beach ID.

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.

28% Complete

28/110 pages complete. Only 82 more pages to go.


Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.