OpenAPI operationId

In OpenAPI, each path can have one or more HTTP method (get, put, post, delete, etc) also known as an operation. To uniquely identify each operation, you’ll use the operationId making it easier to reference and work with API operations programmatically.

Identifying Operations With operationId

To help identify a specific operation among all the defined operations of an API definition, a string field operationId can be used inside an Operation Object (e.g., get) as follows:

This is supported by all major versions of the OpenAPI specification, including v2.0, v3.0, and v3.1.

When to Use OperationId in OpenAPI?

In an operation object, the operationId is an optional field. However, it’s strongly recommended you include one, especially when:

• You have a large API definition with lots of operations. Having an unambiguous identification of API operations is quite important as it aids developers and tools to easily locate and reference the operation.
• You intend to generate client/server code using your OpenAPI definition. The operationId provides a predictable and unique name for each operation, which can be used to generate method names. This makes the code more readable and maintainable.
   
  To illustrate, here is a code sample that makes use of generated code where the operationId, listCharacters, is used to construct a method named ListCharactersAsync.
   
  
• You intend to generate documentation based on the OpenAPI definition. The operationId helps developers quickly locate a specific API operation's corresponding code or documentation. Since operation ids should be unique, they can also be used as anchors in generated documentation.
• You intend to use an external tool or library in your development workflow that relies on your API definition. In such cases, having a unique id for your operations will help seamlessly integrate these tools.

When to Avoid OperationId in OpenAPI?

You can skip adding an operationId if:

• Your API has very few endpoints. A combination of the path and the HTTP method may provide implicit identification in such cases.
• You have no code generation requirements.
• You don’t intend to use your API definition for integration with external tools.

Naming Conventions for OperationId for OpenAPI

Here are some recommended practices when naming your operationId:

• Make it Short: Keep your ID to 30 characters or less and avoid using "a", "an", "the" "and", "for" and similar words as they unnecessarily make names longer.
• Be Unique: Don’t repeat the same name for multiple operation IDs in your OpenAPI defintiion.
• Meaningful: Choose an operationId that reflects the functionality and purpose of the corresponding operation e.g., you can use an id that is a combination of the verb + object/resource e.g., an operation that "gets" a "character" resource should be named getCharacter.
• Consistency is Key: Follow a similar naming conventions for all operation IDs in the API definition.
• No Spaces: Avoid using spaces in your operationId. Also, ensure it does not contain trailing or leading whitespace character, including spaces, tabs, and line breaks.

Example of a bad operationId:

operationId: query device using GET

Example of a good operationId:

operationId: listDevices

OperationId use in Code and Docs Generation

Operation IDs play an important role in code and docs auto generation. To improve the output in such cases, the following practices are recommended:

• Use common programming naming conventions for naming operation IDs e.g. camelCase, PascalCase, or snake_case. Whichever you pick, use it consistently for all operations in the API definition and between different versions of the API definition.
• Stick to alphanumeric characters, hyphens, and underscores only. This ensures compatibility with various programming languages and tools, as any other special characters can pose issues when compiling code, generating code or even URLs (for documentation).
• To avoid conflicts, ensure your operation ids are unique even if compared in a case-insensitive manner or by removing any of the separators like hyphens and underscores e.g. avoid using get-character and getCharacter tools may see them as equivalent.
• When naming operation IDs, capitalize abbreviations 3 characters or less long. For example, CreateHttpServer and GetAPIToken are good. However, CreateHTTPServer and GetApiToken are not. The "3 characters" rule is arbitrary but common in programming.
• When choosing a verb for the operation id, keep in mind the response type and the HTTP verb for the operation itself. We recommend using a convention like Azure's e.g., an operation that gets a list of characters should be named "ListCharacters" and not "GetCharacters".

Referencing Operations With operationId

In OpenAPI v3.0 and above, you can define a design-time link for a response to an operation using the Link Object. To establish a response link with an operation this way, you must reference a predefined operation in the API definition.

One of the ways to do that is to reference its operationId. See an example below where an operation from path /characters/{characterid}/issues is being referenced by the response of an operation from path /characterId/{id} using its operationId getCharacterIssues:

Considerations for referencing by an operationId

Keep the following in mind:

• The operationId you use in a reference link must match exactly the operationId of the operation. Use a case-sensitive comparison for this and avoid typos.
• The operationId should not be an empty string.
• All operations in your API definition should have a unique operationId so your link definition resolves to a single operation.

When to avoid using operationId for referencing?

• You should not use operationId to reference an operation if operationRef is being used already.
• If you need to reference an Operation Object defined in an external document, it is recommended to use operationRef instead to avoid name clashes.

Conclusion

Use operation ids to uniquely identify your operations to easily locate and reference. It is best to use common programming naming conventions when setting these ids to avoid issues when generating code or integrating with any other external tools.

Looking to improve the quality of your OpenAPI definition? Try APIMatic's  VSCode extension with over 1200 validation and linting rules.