[ADE-755] OpenAPI: operationId

Overview

What is operationId?

The operationId is a unique identifier for an operation within an OpenAPI document. It is used to identify a specific operation, allowing for better management and reference in client libraries, code generation tools, and documentation.

Guidance

• SHOULD provide operationId for each API endpoint in OpenAPI document.

  TIP

  operationId values can be used as anchors in API documentation and function names in generated code.

• MUST use a consistent naming convention across the API. This principle recommends camelCase.

  TIP

  The casing strategy MAY be influenced by your team's, organization's, or application's specific definition.

• SHOULD choose names that describe the action performed by the operation. For example, getUser, createOrder, and deleteProduct clearly indicate the operations' purposes.
• MUST avoid redundant prefixes or suffixes that do not add meaningful information. For instance, getUser is preferred over userGet.
• SHOULD ensure the operationId reflects the context of the operation within the API. For example, in an API managing a library, borrowBook and returnBook provide clear context.
• MAY include audience information in the operationId to avoid collisions when necessary. For example, getUserForPublicExternal and getUserForComponentInternal.
• DRAFT For consistency, it is required (MUST) to include the following keywords in the operationId:
  • get
  • list
  • update
  • delete
  • create
  • replace
  • add
  • set
  • unset
  • check
  • add (distinct from create, primarily for adding a sub-resource to a main resource)
  • remove (distinct from delete, primarily for removing a sub-resource from a main resource)
• DRAFT Use the appropriate verb based on the scenario

Operation Verb	Request	Status Code	operationId	Description
get	GET /users/{id}	200	getUser	Retrieve a user
list	GET /users	200	getUsers	Retrieve a list of users
create	POST /orders	201	createOrder	Create a new order
update	PUT /users/{id}	200	updateUser	Update user information
delete	DELETE /users/{id}	204	deleteUser	Delete a user
create	POST /users	201	createUser	Create a new user
replace	PATCH /users/{id}	200	replaceUser	Replace user information
add	POST /orders/{id}/items	201	addItemToOrder	Add an item to an order
set	PUT /orders/{id}/items/{itemId}	200	setOrderItem	Set an order item
unset	DELETE /orders/{id}/items/{itemId}	204	unsetOrderItem	Unset an order item
check	GET /orders/{id}/items	200	checkOrderItems	Check order items
add	POST /users/{id}/roles	201	addUserRole	Add a role to a user
remove	DELETE /users/{id}/roles/{roleId}	204	removeUserRole	Remove a role from a user

• Specific operations may (MAY) not follow the established convention. This is typically the case for actions paired with the POST method, similar to gRPC.

Example

Here is an example of an OpenAPI document snippet with properly defined operationId values:

paths:
  /users:
    get:
      summary: Retrieve a list of users
      operationId: getUsers
      responses:
        '200':
          description: A list of users
  /users/{id}:
    get:
      summary: Retrieve a user by ID
      operationId: getUserById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A user object
  /orders:
    post:
      summary: Create a new order
      operationId: createOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '201':
          description: Order created

Related ADEs

• ADE-24: Versioning Mechanism
• ADE-751: New OpenAPI document
• ADE-752: OpenAPI API audience

References

• OpenAPI Specification
• IBM API: operation

Changelog

• 2024.09.30: Add operation keywords
• 2024.10.17: Add operationId usage tip