Skip to content

operationId in OpenAPI: what it is for and how to name it

Last checked and updated

operationId is an optional string that names one operation. The specification requires it to be unique among all operations of the API and notes that it is case-sensitive. Its value never appears in a request: it exists for tools.

paths:
  /orders/{orderId}:
    get:
      operationId: getOrder

Who reads it

ReaderUses it as
Client and server generatorsthe method or function name: client.getOrder(id)
Some documentation toolsthe anchor of the operation's section, so links stay stable when the path changes
OpenAPI linksthe way one operation points at another (operationId: getOrder)
Mock servers, tests, gatewaysa way to select an operation; a mock's error names it: "The request does not match createItem"
Agents and MCP toolscommonly the tool's name, when an API description is turned into tools

Without an id, a tool that needs a name has to invent one from the method and path, for example getOrdersOrderId, and different tools invent different ones.

Naming rules

  1. Unique in the whole API, even when the description spans several files. A duplicate is an error: "Every operation must have unique operationId".
  2. Letters and digits only, starting with a letter is this page's recommendation: the id often becomes an identifier in code. The linter is more lenient, it only refuses characters that are invalid in a URL (hyphens pass, and Spectral's own documentation suggests lower-hyphen-case).
  3. verb + resource: listOrders, createOrder, getOrder, updateOrder, deleteOrder, listOrderItems. The list and the single item differ by verb and by number.
  4. One case style for the whole API. Generators convert to their language's style, so get_order and getOrder in one description can collide after conversion.
  5. Stable. Renaming changes generated method names for every consumer.

What a linter says

An id with spaces passes the uniqueness check and still gets a warning:

$ apigit lint ops.yaml
  32:20  warn   operation-operationId-valid-in-url  operationId must not contain characters that are invalid when used in URL.  (paths./orders/{orderId}/items/{itemId}.get.operationId)

That operation was written operationId: get order item. A missing id is reported by the rule operation-operationId, and the readiness score for AI agents counts both properties separately:

$ apigit score ex.yaml
ex.yaml  89 / 100
  3 of 3  Operations have an operationId
  3 of 3  operationIds are unique

Adding ids to an existing API

Add them in one change, by the scheme above, and treat that change as the moment the names become public. If clients are already generated from the description, check what names the generator used so far: choosing ids equal to those names means no method is renamed.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish