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 appWhat 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.
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
- 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.
- Type a Name, such as
Checkout Service. - Choose its Type.
- Optionally add a Logo, a Description, an Owner team and Tags. Separate tags with commas:
commerce, tier-1. - Press Create system.
The new system appears on the map without any connections. Drag its + handle onto another system to connect them.
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).
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.
- Open the API from the system's APIs tab (or add a new one).
- Turn on Publish as public API.
- 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+Kon 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.
Related
- The system mapYour systems and the connections between them on one canvas, coloured by contract health, with a table and a Connections view.
- APIs and contractsDeclare what providers offer and what consumers expect. Rabbinatix pairs them into contracts and checks them field by field.
- Public APIsPublish an API for other organizations to depend on, subscribe to theirs with real contracts, and see which fields your subscribers rely on.
- Members and rolesInvite people to your organization, give them a role, build your own roles, group people into teams and handle access requests.
