RabbinatixDocs
Sign inGet started

Map your systems

Systems

Create the apps and services you build or depend on, give them owners and tags, and find any system or API again.

Open Systems in the app

What a system is

A system is one piece of software you build or depend on: a website, a mobile app, a service, a database, a queue or a partner's API. A system can offer APIs and call other systems' APIs at the same time.

Systems are the boxes on the system map. You never draw a line between two systems by hand. A connection appears as soon as one system declares that it calls an API of another. See APIs and contracts.

Types of systems

Pick the type that fits. It sets the icon and which tabs the system page shows.

TypeUse it forExtra tab
Web frontendA website or web app—
Mobile appAn iOS or Android app—
Backend serviceAn API server or microservice—
WorkerA background job or scheduled task—
DatabaseA database that logic reads and writesResources
Queue / event busA message queue or event streamResources
External APIA public API of another organization that you subscribed toResources

You can't pick External API in the form. Those systems come from subscribing to a public API (see below) or from a ready-made system map in the Store.

Create a system

  1. Open Systems in the sidebar and press New system. On the map, press System in the toolbar, or right-click the canvas and choose Add system here.
  2. Type a Name, such as Checkout Service.
  3. Choose its Type.
  4. Optionally add a Logo, a Description, an Owner team and Tags. Separate tags with commas: commerce, tier-1.
  5. Press Create system.

The new system appears on the map without any connections. Drag its + handle onto another system to connect them.

NoteThe logo is kept in this browser for now, so other members may still see the type icon.

Edit or delete a system

Open the system and press Edit in its header. The same form opens with Save.

To delete it, open the Settings tab and press the delete button under Delete system. The confirmation lists everything that goes with it. Its endpoints are removed, and every consumer that called its APIs becomes Unresolved. Its move requests go too, and its chat channels (the system's own and those of its connections) are archived.

Owners, teams and tags

The owner team says who answers for a system. Teams are made in Members and teams, on the Teams tab. A system's team shows on its card, in its header and in the API catalog, and it names the owners to notify when a change would break something.

Tags are free labels. The systems list shows the first two on each card, and the system header shows all of them.

The system page

The header shows the system, its team and tags. Edit changes its name, kind, team and tags; Discuss opens a chat about it; the … menu has Add an API, Add a dependency…, Contract watcher, Show on the system map, Releases and What’s linked (everything linked to it, and what stops working if it goes down).

TabWhat it shows
APIsThe APIs this system provides, grouped by API version, with who uses each one. Switch between List and Reference (their docs). Click a row to open the API's page; point at it for New version and + Logic
UsesThe APIs it calls, grouped by the system that provides them, with each contract's status
LogicThe logic that runs in it (Logic)
FlowsBusiness flows that start in it or pass through it
ResourcesTables, queues or operations of a database, queue or external API
TicketsOpen tickets about it
RunningThe running system: Health checks one per environment (Health checks), the Test server, a stand-in for its APIs (Test server), and Real API, to send requests to its running API and check the answers (Real API)
SecurityThe security checks on its APIs
SettingsLogo, its code repository, its public APIs, export and delete

Visibility and public APIs

A system and its APIs are private to your organization or project by default. You don't publish a whole system: you publish one API at a time, and the rest of the system stays private.

  1. Open the API from the system's APIs tab (or add a new one).
  2. Turn on Publish as public API.
  3. Fill in a Public name, a Category and a Description, then save.

All versions of the API are shared: the same method and path in v1, v2 and any later version count as one API, so a new version is public as soon as you add it. Each version's deprecation and shutdown date go along. Your internal consumers, teams and history stay private. Public APIs carry a Public badge on the APIs tab, and the system's Settings tab lists them. Turn the switch off and save to take an API back. See Public APIs.

External systems

When your organization subscribes to another organization's public API on Public APIs, it appears as a system of type External API, marked "Public API · subscribed" in the list. You can declare expectations against it like any other provider, but you can't add endpoints to it, edit it or delete it here: its owner keeps it up to date.

Find systems and APIs

  • Systems list. Type in Search systems…, pick a type chip, or choose a team. Each card shows how many APIs it provides and consumes and how many systems depend on it.
  • API catalog. API catalog in the sidebar lists every API your organization or project provides, by system, with its version, lifecycle, consumers, tickets and health. Search by path, summary, system or field. Show one system with the System list, and filter with With issues, Planned, Deprecated or Unused. Click a row to open the endpoint.
  • Search everywhere. Press Ctrl+K (Cmd+K on a Mac) to search systems and APIs from any page.
  • What’s linked. To see what a system is linked to, use What’s linked. See The system map.