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.

What is an operationId?

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.

The 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.

Make operationId work for 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 operationId is 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 operationId is 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 operationId follows a naming convention and is consistent across the API surface.
• API Gateways use the operationId to 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 getUserAccounts and 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.

Learn more

• Turn on the operation-operationId-unique rule in your linting setup and make sure you're writing good operationIds in your APIs.
• Browse our visual OpenAPI reference to learn more about operation and its fields.
• Level up your OpenAPI descriptions further by reading our post about Markdown in OpenAPI.