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
| Reader | Uses it as |
|---|---|
| Client and server generators | the method or function name: client.getOrder(id) |
| Some documentation tools | the anchor of the operation's section, so links stay stable when the path changes |
OpenAPI links | the way one operation points at another (operationId: getOrder) |
| Mock servers, tests, gateways | a way to select an operation; a mock's error names it: "The request does not match createItem" |
| Agents and MCP tools | commonly 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
- Unique in the whole API, even when the description spans several files. A duplicate is an error: "Every operation must have unique operationId".
- 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).
- verb + resource:
listOrders,createOrder,getOrder,updateOrder,deleteOrder,listOrderItems. The list and the single item differ by verb and by number. - One case style for the whole API. Generators convert to their language's style, so
get_orderandgetOrderin one description can collide after conversion. - 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.