Getman
العربيةDownload

Contracts

Export a project as an OpenAPI 3.1 contract, compare two contracts for breaking changes, and design an API in the app.

A contract describes what an API accepts and returns. Getman builds one from your saved requests, exports it as OpenAPI 3.1, and compares two versions to show what a change breaks. The team’s current contract lives in contracts/openapi.yaml in the workspace, and change packages are checked against it.

Export a contract

  1. Open the project menu in the title bar and choose Export project…. You can also run Export OpenAPI contract… from the command palette (⌘K).
  2. Choose OpenAPI 3.1 and save the file.

The export is deterministic: the same project always gives the same file, with keys and paths sorted. Secret values, client secrets and secret variables are removed before export, and only the names of auth schemes are kept.

How requests become operations

Getman OpenAPI 3.1
The leading {{base_url}} in a URL A server, with the default taken from the environment when the value is not secret
:id or {{id}} in a path A required {id} path parameter
Request name summary
Enabled query parameters and headers Parameters with required: false
JSON body application/json with a schema inferred from the body
Response examples One response per status, with examples
Requests sharing a method and path One operation. The response examples of all of them are merged
Auth Security schemes and a per-operation security entry

Schemas are inferred from the examples you saved, so they are a starting point, not a specification. Every property in a single example becomes required. A change that depends on an inferred schema is rated potentially breaking rather than breaking, so review the inferred schema before you rely on it.

Compare two contracts

  1. Open the command palette (⌘K) and choose Compare API contracts…. The Compare contracts view opens.
  2. For each side, choose This project to use the project’s current requests, or OpenAPI file and then Choose file…. One side can stay on this project.
  3. Read the diff. It lists each change with its operation, and you can filter by severity or by side (request or response).
  4. Each change shows its before and after values. Copy as text copies the whole diff.

Each change has a severity, given separately for the request side and the response side:

Severity Meaning
Breaking Existing clients fail
Potentially breaking Some clients may fail, depending on how they use the field
Non-breaking Existing clients keep working
Unknown The change cannot be classified, usually because a schema is missing on one side

The rules come from 43 kinds of change. A few examples:

Change Request side Response side
Endpoint added Non-breaking Non-breaking
Endpoint removed Breaking Breaking
Required parameter added Breaking Not applicable
Optional parameter added Non-breaking Not applicable
Response status removed Not applicable Breaking
Response status added Not applicable Potentially breaking
Required property added to a request Breaking Non-breaking
Property removed from a response Not applicable Breaking
Enum value removed from a request Breaking Non-breaking

The same change can be breaking for a request and harmless for a response. A property that becomes required is breaking for a sender, because the sender must now send it, and harmless for a consumer, because the server promises it.

Design an API

API design is an editable OpenAPI 3.1 document for the project. Open it from the rail, or from Open API design in the command palette.

  • Generate builds the design from your saved requests.
  • Merge adds operations the design does not have. It never changes existing ones.
  • Import reads OpenAPI 3.0 or 3.1, as JSON or YAML. Swagger 2.0 is refused, so convert it first.
  • Create requests turns the design into a new collection. The project’s base_url is kept.
  • Compare diffs the design against your requests.

The design is saved in the app, and it is never written to contracts/openapi.yaml. That file stays the last published contract until you export again.

Limitations

  • Parameters are exported as strings, because Getman stores parameter values as text.
  • readOnly, writeOnly, descriptions, defaults and examples are not compared.
  • oneOf and anyOf are compared as a whole, so the severity is unknown.
  • Callbacks, webhooks, links and cookie parameters are not exported.
  • The export’s info.version defaults to 1.0.0, because a project has no API version field.
  • In the design, allOf, oneOf and anyOf are edited in the JSON tab, not in the schema form.

Next steps