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 appThe statuses
Every contract has one status. Colour is never the only sign: each status also has an icon, a line style and a word.
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:
- Broken
- Design conflict
- Warning
- Unknown
- Unresolved
- Planned
- 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
Mismatch codes
The contract policy
If the defaults are too strict or too loose for you, change them for the whole organization or project.
- Open Settings and the Contract policy tab.
- Choose This organization for every project, or This project for the open project only.
- Find the check. Each row shows its name and its default; hover the name to see its code (the one in the table above).
- For the organization, under Your policy, choose Breaking, Warning, Info or Off. Default goes back to the default.
- 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.
Related
- APIs and contractsDeclare what providers offer and what consumers expect. Rabbinatix pairs them into contracts and checks them field by field.
- The system mapYour systems and the connections between them on one canvas, coloured by contract health, with a table and a Connections view.
- Retiring APIsRetire an API with a shutdown date and a replacement, and follow every consumer until they have all moved off.
- Automatic tickets and automationTickets that open and close themselves when a contract breaks, a test case fails or a service goes down, plus request tickets, access tickets and your own automation rules.
- SettingsEvery tab of Settings: your profile and the organization, single sign-on, the uptime commitment and security review, appearance, health checks, roles, tickets, chat and contract policy. Members and teams, Usage and billing, Environments and Trash have their own sidebar entries.
