RabbinatixDocs
Sign inGet started

Map your systems

Contract statuses

What each status means, how one contract colours a connection and a system, how to read a contract, and how to tune the checks.

Open System map in the app

The statuses

Every contract has one status. Colour is never the only sign: each status also has an icon, a line style and a word.

StatusLineMeaning
HealthySolid greenMatched, deployed, every check passes
WarningSolid amberIt works, with small issues such as a format difference or a deprecated API
BrokenSolid redA deployed provider no longer gives the consumer what it needs
PlannedDashed blueThe provider endpoint exists but isn't deployed yet, and it fits
Design conflictDashed orangeThe planned provider would break the consumer once deployed
UnresolvedDotted greyNo provider offers what the consumer calls
UnknownDashed greyNot checked yet

Planned, conflict and broken

While a provider endpoint is To do or In progress, a disagreement is a design conflict to fix before it goes live. Once it is Deployed, the same disagreement makes the contract Broken. A design conflict still blocks the safety check when a caller runs in the environment it checks, and saving or publishing the change asks first: "Breaks 1 caller once deployed?". See APIs and contracts.

How statuses roll up

A connection takes the worst status of its contracts, in this order:

  1. Broken
  2. Design conflict
  3. Warning
  4. Unknown
  5. Unresolved
  6. Planned
  7. Healthy

The counts are always shown, so a red line can still say that nine of ten APIs are healthy. A system's badge takes the worst status of all its connections, as consumer and as provider. The System map item in the sidebar counts broken contracts, and the Dashboard totals every status in the organization or project.

The contract detail

Click a row on a connection page to open its contract. You see:

  • The API and its status. Re-run verification checks it again.
  • A banner when needed. Unresolved shows near-miss suggestions with Use this, a button to create a planned endpoint, and Open API requests. Planned and Design conflict say Provider not deployed yet. A deprecated provider shows its shutdown date.
  • Its open tickets and what it is linked to.
  • A strip of checks for the request and the response.

The tabs:

  • Comparison lines up every field, consumer on the left and provider on the right, with a mark per row. Turn on Only show differences, then click a highlighted row to see its mismatch.
  • Mismatches lists every mismatch, each with Create ticket.
  • History shows changes to this contract over time.

Each mismatch shows its severity, a plain title, its code, the Consumer side and the Provider side, and where in the API it is. Its buttons:

  • A quick fix that changes the expectation, such as Stop relying on this field, Accept null or Use provider auth.
  • Explain, for a short explanation with a fix for each side.
  • Edit consumer and Edit provider.

Severities

SeverityEffect
BreakingMakes a deployed contract Broken, or a planned one a Design conflict
WarningMakes the contract Warning
InfoShown, but doesn't change the status

Mismatch codes

CodeDefaultExample
METHOD_MISMATCHBreakingThe methods differ (only on a hand-made link)
HEADER_MISSINGBreakingThe provider requires X-Tenant-Id and the consumer doesn't send it
HEADER_OPTIONALITYWarningThe consumer needs ETag and the provider may leave it out
HEADER_VALUE_MISMATCHBreakingapplication/json against text/plain
QUERY_PARAM_MISSINGBreakingThe provider requires ?page
PATH_PARAM_TYPEBreaking{id} is an integer on one side and a uuid on the other
CONTENT_TYPE_MISMATCHBreakingJSON against form data
AUTH_MISSINGBreakingThe provider requires a bearer token and the consumer sends none
AUTH_TYPE_MISMATCHBreakingBearer token against API key
AUTH_SCOPE_MISSINGWarningThe provider requires scope users:write
AUTH_UNNEEDEDInfoThe consumer sends a token the provider ignores
STATUS_MISSINGBreakingThe consumer relies on 201 and the provider only returns 200
STATUS_UNHANDLEDWarningThe provider may return 202 and the consumer doesn't handle it
ERROR_STATUS_UNDECLAREDInfoThe consumer handles 409 and the provider never returns it
TYPE_MISMATCHBreakinguserId is a string on one side and a number on the other
NULLABILITYBreakingThe provider may return null for name
FIELD_MISSINGBreakingThe consumer reads email and the provider doesn't return it
FIELD_OPTIONALITYBreakingThe consumer needs email and the provider may leave it out
FIELD_UNKNOWNWarningThe consumer sends nickname and the provider doesn't accept it (Breaking when the provider allows no extra fields)
FIELD_EXTRAInfoThe provider returns createdAt and the consumer ignores it
ENUM_VALUE_UNHANDLEDBreaking in a request, Warning in a responseThe provider may return status: "archived"
FORMAT_MISMATCHWarningemail against uri
ENDPOINT_DEPRECATEDWarningThe provider endpoint is deprecated
ENDPOINT_SUNSETBreakingIts shutdown date has passed

The contract policy

If the defaults are too strict or too loose for you, change them for the whole organization or project.

  1. Open Settings and the Contract policy tab.
  2. Choose This organization for every project, or This project for the open project only.
  3. Find the check. Each row shows its name and its default; hover the name to see its code (the one in the table above).
  4. For the organization, under Your policy, choose Breaking, Warning, Info or Off. Default goes back to the default.
  5. For a project, under In this project, choose a level, or Same as organization to follow the organization. Below each choice you see where the level comes from.

A level set in a project wins over the organization's in that project only. A check the project doesn't set follows the organization, also when the organization changes it later.

Every contract is checked again straight away. For example, set Field not accepted (FIELD_UNKNOWN) to Breaking if your providers reject unknown fields. Changing the policy needs the permission to manage it (see Members and roles).

Contract policy history below the table lists every change with who made it. Compare shows it against the policy now, and Restore puts it back. A restore is recorded as a change too.