RabbinatixDocs
Sign inGet started

Map your systems

APIs and contracts

Declare what providers offer and what consumers expect. Rabbinatix pairs them into contracts and checks them field by field.

Open API catalog in the app

Consumers and providers

Every API is described from two sides.

  • A provider endpoint says "I answer this request with this shape". It belongs to the system that offers the API.
  • A consumer expectation says "I call this API on that system and expect this shape back". It belongs to the system that calls it.

You never create a contract yourself. Rabbinatix pairs each expectation with the matching provider endpoint and checks that the two agree. That pair, with its result, is the contract. You can also import both sides. See Import and export.

Declare a provider endpoint

  1. Open the system and stay on APIs. Press Add an API.
  2. Under Basics, choose the Method and type the Path, such as /api/v2/login. Write path parameters as {id}.
  3. Leave API version empty to take it from the path (/v2/ gives v2, otherwise v1), or type one.
  4. Add a Summary and pick a Lifecycle: To do, In progress or Deployed.
  5. Fill in Request and Responses (see below).
  6. Press Create endpoint, or Ctrl+S. Esc closes the editor.

Declare a consumer expectation

  1. On the connection page, press New expectation. You can also use Add a dependency on the Uses tab.
  2. Check Calls system: the provider it calls.
  3. Fill in the method, path, request and the responses it handles. Mark the one it relies on with Expected success response.
  4. Press Declare expectation.

To save typing, press Generate from code and paste a curl command or a fetch, axios or Angular HttpClient call. Add a TypeScript interface to fill in the response.

Request and response

PartWhat to fill in
AuthenticationNone, Bearer token, Basic, API key or OAuth 2, with Scopes
Content typeSuch as application/json
Path parametersOne per {name} in the path, with its type
Headers and Query parametersName, whether it is required, and a fixed value if it has one
Request bodyThe shape that is sent
ResponsesOne card per status code. Add one with the +200, +404 chips. Each has a body and headers.

Write shapes

Bodies use a short text form:

email: string(email)
password: string
remember?: boolean
profile: { name: string, age?: integer }
tags: string[]
status: enum(active, archived)

A ? after a name makes the field optional. Add | null after a type when the value may be null. string(email) adds a format. Press Types above a body to see every type, format and way to combine them. To start from real data, press From JSON, paste an example and press Infer shape. Format tidies the text.

How matching works

A consumer and a provider are paired when all of these are the same:

  • the provider system (the one the consumer calls)
  • the method
  • the path, after it is normalised
  • the API version

Normalising ignores letter case, a trailing slash and the query string, and treats every parameter alike. So /api/v2/Users/:id/ and /api/v2/users/{userId} match. A v1 consumer is only matched with v1 of the provider.

When nothing matches, Rabbinatix suggests near misses: the same path with another method, the same path in another version ("Available in v2"), or a path one typo away ("Did you mean …?"). Press Use this in the contract, or Apply in the editor, to change the expectation to that endpoint.

Live checks while you edit

The editor checks your change before you save it.

  • On an expectation, Live check shows the contract status it would have and its first mismatches, or "Matches the provider on every field."
  • On a provider endpoint, Impact on consumers lists every consumer with its status before and after. If your change breaks one, it says so and suggests Draft mode.

Design first with APIs not built yet

You don't have to build an API before others can depend on it. A provider endpoint whose lifecycle is To do or In progress counts as not built yet. Consumers match it as usual, and their contract is Planned, or Design conflict when the two sides disagree. Nothing counts as broken on the map until it is deployed, but a design conflict asks first when you save or publish it, and the safety check blocks it where the caller already runs.

To turn an unresolved call into a planned endpoint, press Not built yet on its connection row, or the button in the contract that creates one. When you create a provider endpoint someone asked for, turn on Also create an API request and pick who it is Requested by.

The API request board

Unresolved calls and API requests land on the board, in the API requests view for the provider. Its columns are Requested, To do, In progress and Deployed. Moving a request to a column sets the endpoint's lifecycle, so consumers see the progress on their contracts. Open API requests in a contract takes you there. Set Needed by (optional) on an expectation to say when you need it. See The board.

Compare a provider with its consumers

In the endpoint editor, press Compare with consumers on a provider endpoint, or Compare with provider on a consumer expectation. The Compare page puts the two side by side, field by field.

  • The provider is always on the left. On the right, pick which consumer to compare. From a consumer expectation, that expectation is already picked.
  • Highlighted rows don't match. Click one to see what is wrong, with Explain and, where it helps, a fix.
  • Only show differences hides the rows that match. Open contract opens the contract on its connection page.
  • If one side is missing, that side says why: nobody calls the API yet, or the provider doesn't declare the call yet.

More in the endpoint editor

  • Implement with logic creates the logic behind a provider endpoint. See Logic.
  • The History, Consumers & field usage and Test server tabs cover versions, who reads what and the test server.
  • Details, meanings after #, examples after = and When it happens are the API's docs. See Document your APIs.