Writing API descriptions requires thinking about the endpoints in your API, and how developers interact with them individually and with the API as a whole. Each endpoint and HTTP verb combination make an
operation, and contribute to the overall experience. Beyond the per-operation summaries and descriptions, and the data payloads, we rarely pay attention to the hidden gem of API design -- the
operationId. Today I'll show you how this small field can have a big impact on developer experience, and how to use it to good effect.
From the OpenAPI specification:
Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
operationId field is a unique way of referring to a specific operation in an OpenAPI description. It's easy to overlook, since the specification does not require the field. Redocly CLI's recommended ruleset includes checks for the
operationId being required, unique and URL-safe - so you can see that we feel pretty strongly that it's a good feature to include! In fact, it's used by the majority of the modern tools that consume OpenAPI descriptions and should be a consideration for API designers everywhere.
Having a good identifier, unique to each operation, can deliver some unexpected benefits. It's subtle, because in plenty of OpenAPI usage the
operationId isn't visible at all, but a unique and descriptive handle for each operation is useful in many situations. Get this right, and your users (and your future self) will thank you.
Thoughtful use of
operationId is an indication of good API design. It shows consideration for multiple applications of the API, and improves the developer experience for consumers and producers alike. Before you decide on a naming convention though, it might help to think about where this identifier is used in practice:
- In API documentation, the
operationIdis often used as a URL fragment so that a user can link to exactly the correct endpoint in a long API documentation page. When a user bookmarks multiple endpoints to refer back to, a meaningful name helps them navigate to the right place easily.
- When generating code, both for clients and servers, the
operationIdis often used in method or function names. Picking good IDs for your operations when designing an API, therefore, enables much smoother API integrations, especially if every
operationIdfollows a naming convention and is consistent across the API surface.
- API Gateways use the
operationIdto configure endpoints for rate limiting, authorization, and other similar features. Meaningful names makes life easier for developers and makes misconfiguration less likely.
Though subtle, the under-appreciated
operationId has an outsized impact on developer experience and can enhance API design when used thoughtfully.
To begin, try using a pattern of
verb-noun, for example
getEvents. Add more specific words in, as needed, for clarity. For example instead of just
getAccounts you might have endpoints
getAdminAccounts. Don't be afraid to break out of the CRUD (Create, Read, Update and Delete) set of verbs to choose words that more clearly describe what is happening:
archiveProduct would be a good example here.
Test out your naming informally by asking someone "what would you expect an API endpoint named [your name idea] to do?". Sometimes the names we think are perfectly obvious are not so obvious to others, and this test is a great way to identify those situations before they are baked into a public API!
Naming conventions will differ between organizations and use cases, but whatever you choose, being consistent across your API and making sure that every
operationId is unique is the most important thing to aim for.