Defining & promoting operations

Most operations come from an imported OpenAPI spec. A defined operation is one you add yourself, by hand or through a Postman or HAR import: it exists in your project, not in the spec. Promotion is how a defined operation becomes part of the spec.

Defining an operation

In the schema sidebar, use + on a resource (or the API) and give the method, path and operationId. From the CLI:

craftr schema define Pet adopt --method POST --path /pet/{petId}/adopt --operation-id adoptPet -a petstore-api
craftr schema undefine Pet adopt -a petstore-api

A defined operation is marked defined in the sidebar. Its method, path and operationId are editable in the operation header.

Editing its contract

For a defined operation, the Definition tab is an editor: the contract you see is the whole contract, there is no spec underneath.

  • Summary and description.
  • Parameters: name, location (path, query, header, cookie), type, required and description. Path parameters are always required; a {placeholder} in the path without a parameter is flagged with a one-click Add it.
  • Request body: add or remove it, its content type, whether it's required, and its JSON schema.
  • Responses: add or remove status codes (100–599 or default), their description and body schema.

Schemas are edited as JSON in the right-hand pane; invalid JSON is shown and not saved. Switch the pane to Preview for the usual example and schema tree. Every change can be undone.

The Definition tab of a defined operation, with editable parameters and the JSON schema editor

Operations that come from the spec keep the read-only Definition tab and the Customize section: your edits there are overrides on top of the spec, which re-imports keep track of.

Promoting to the spec

Once the contract is right, promote it. The operation, with its parameters, request body and responses, is written into spec.imported.json and becomes a regular spec operation: same resource, same name, same requests and workflows.

Promote one operation, a resource, or everything defined in the API:

craftr spec promote -a petstore-api --operation Pet/adopt
craftr spec promote -a petstore-api --resource Pet
craftr spec promote -a petstore-api

In the app: Promote to spec in a defined operation's header or menu, Promote defined operations to spec in a resource's menu, or the button in the API header. Each asks for confirmation, and the whole promotion is a single undo step.

The promoted operation is completed with what OpenAPI requires and a defined operation may lack: a default response when there is none, and a required path parameter for each {placeholder}.

The API now owns its spec

After a promotion, api.json carries "specSource": { "type": "self" }: API Craft is the author of this spec, there is nothing upstream to re-import. An API with no specSource at all means the same thing.

Promoting detaches an upstream source. If the API re-imports from a file or URL, promotion replaces that source with self, and the next import would no longer find the promoted operations upstream. The app shows this in the confirmation and the CLI prints a warning. To import from a file or URL again later, pass it explicitly: it becomes the source again.

Only defined operations are promoted. Overrides you made on operations that came from the spec stay overrides, so you can still tell your local changes from the imported contract.

Why promotion is explicit

An imported contract is inferred from samples, and its resource names are a best guess. Writing it straight into the spec would make it authoritative before anyone reviewed it. So an import only creates defined operations; you correct them, then promote when you're satisfied.