If you write API documentation, you probably use the OpenAPI specification (OAS, formerly Swagger), one of the most popular formats for creating API references. After all, how many modern API tools can you think of that don’t accept OAS files? They use them to display documentation, set up endpoints for testing, generate clients, and much more.
The OAS endpoint summary is an important element of the OAS file that is often neglected by doc writers. While these summaries might not contain all the necessary details about an endpoint, they’re still crucial to the user experience. Think about it – they are one of the first things API consumers see. Hence, if they’re poorly written, they can cause major confusion and headaches.
So, if your endpoint summaries look similar to those in the picture below, don’t fret. I’ve got your back with these five steps on how to make them more professional, helpful, and consistent. So, let’s step up your API reference game!
Step 1: Write short sentences
Your API users should be able to skim the OAS endpoint summaries to get an overview of what’s available or to quickly find a specific endpoint.
Of course, the more you write, the more challenging it becomes to grasp information.
So this first step is about making the summaries short and sweet by doing the following:
- Reduce all summaries to the most critical information and save the rest for the endpoint description.
- Rephrase summaries into sentences. I like to start with a capital letter and end with a period, but that’s more of a personal preference.
And here’s the result. See how I drastically shortened the text for the PUT endpoint and how writing complete sentences already looks way more user-friendly and professional.
Step 2: Be action-oriented
Your API consumers use your endpoints to DO something and achieve specific goals. Therefore, make sure that the purpose of an endpoint is apparent by putting the respective verb at the beginning of the summary sentence.
I like to address the user directly and tell them what they can do with an endpoint rather than what it does. Let me show you what I mean with an example:
Endpoint summary that tells the user what the endpoint does:
- Gets a list of todos. (This endpoint gets a list of todos for you.)
Endpoint summary that tells the user what they can do with it:
- Get a list of todos. (You get a list of todos from this endpoint.)
When documenting APIs, I usually opt for the second approach. However, if you prefer the first option, go ahead – just be sure to stay consistent and don’t mix them!
Most of my endpoint summaries have already started with a verb, so here’s the updated text:
Step 3: Match your verbs to your method
Make sure your verbs match the method the endpoint accepts (GET, PUT, POST, etc.), so it’s clear what the endpoint is doing. We cannot control which tool users use to load our OAS file and how the tools render its content. Thus, the endpoint method may not be as clearly visible as, for example, in my images (which are modeled after the Swagger editor).
Be specific with your verbs and use ones that best reflect the endpoint’s functionality. Personally, I like to use the same verbs whenever possible to make the text easier to scan, even if it’s repetitive.
However, this also means that I recommend using synonyms sparingly, as they can be confusing and may not represent the functionality of an endpoint. For example, it’s not always correct to replace “create” with “save” since “save” could also be used with PUT or PATCH.
So in this step, I replace the starting verbs of each sentence with a better-fitting one. Note that I start with “Delete” and “Get” for endpoints that accept methods with the same name – I don’t care if this introduces repetition as long as I can ensure that the summaries make sense all by themselves.
Step 4: Follow a pattern
You can make your summaries even easier to digest by making them predictable. To do this, write each sentence in a specific pattern that helps users quickly pick out what they need.
But that’s not all: consistency of language, grammar, and spelling also helps make API endpoint summaries easy to read, understand, follow, and predict.
You can see the result of this step in the image below – here’s what I did:
- Established a structure and stuck to it
- Verb + count + resource + query parameter(s)
- For example: Get a todo by ID.
- Used consistent spelling for words like “todo”
Step 5: Make endpoints distinct
Finally, if your API has two or more similar endpoints, you must ensure the OAS endpoint summaries help consumers tell them apart.
As distinguishers, you can use an endpoint’s request parameters, such as IDs and the accepted method. But when you have many many endpoints, even the best summaries can’t prevent confusion. This is where OAS tags come in handy. You can learn more about them in this article.
In our example, we have two DELETE and two GET endpoints that might be challenging to distinguish. So let’s change that!
Look at the image below; I added the request parameter ID to the summaries to help distinguish them (I am still following my structure!).
Now it’s your turn to create better OAS endpoint summaries!
Once you have your OAS endpoint summaries down to a simple and digestible format, you can either leave them as they are or use them as a basis for further expansion.
Especially for large APIs with many endpoints, you may need to add more information to your endpoint summaries to make them as helpful as possible.
However, sticking to the five steps outlined in this article can prevent your text from getting cluttered again.
No responses yet