Work as a team
Public APIs
Publish an API for other organizations to depend on, subscribe to theirs with real contracts, and see which fields your subscribers rely on.
Open Public APIs in the appWhy public APIs
Most APIs you depend on belong to other companies. A public API lets one organization offer an API and others subscribe to it. Subscribers declare what they use, get contract status like any internal connection, and hear about changes before they break. The provider sees which fields subscribers rely on, so it knows what is safe to change.
Open Public APIs in the sidebar. It has three tabs: Browse public APIs, Subscriptions and one for the APIs your organization publishes.
Publish an API
You publish one API at a time, with all its versions. The rest of the system stays private.
- Open the API from its system's APIs tab. You can also do this while adding a new API.
- Turn on Publish as public API.
- Fill in the Public name, Category and Description.
- Save.
In a project that saves edits as drafts, the API becomes public when your changes are published to Development. Until then, Published by says it is not public yet.
Versions are matched by method and path without the version part: GET /api/v1/orders/{id} and GET /api/v2/orders/{id} are one API. A version you add later is published with it, as a version that is still coming until it is live. When you change a version, the published copy is updated. To stop offering the API, turn the switch off and save: subscribers keep their copy but get no more changes, and Rabbinatix asks first when someone subscribes.
The system's Settings tab lists its public APIs.
Subscribe to an API
- Open Public APIs and stay on Browse public APIs.
- Search for an API, or click View contract to see its endpoints and changelog first.
- Click Subscribe.
- Under Consuming system, pick your system that calls this API.
- Click Subscribe & choose endpoints, then choose the endpoints your system uses.
The API now appears on your system map as an external system named after the organization and the system it comes from. Other APIs you subscribe to from the same system join that one. Rabbinatix checks your expectations against it like any other provider, so a change that breaks you turns your contract BROKEN. See contract statuses.
Manage subscriptions
The Subscriptions tab lists each public API you use, which of your systems uses it, the contract status and since when. Open goes to the connection. Unsubscribe removes it after you confirm. Unsubscribing needs the Public network permission.
When its publisher takes an API off the public list, it stays here marked No longer public. When the organization that published it deletes it (with its workspace or project), it is marked Deleted by its organization and you get one notification. Either way you keep your copy until you unsubscribe, but it gets no more changes.
If you haven't declared any expectations yet, the row says No expectations yet. Until you do, there is nothing to check.
Consumer insights
On the tab for your published APIs, each API shows how many organizations subscribe. Under Consumer insights you see which response fields subscribers read, and how many of them read each one.
The counts come from subscribers' declared expectations. They are anonymized and aggregated: you see counts, not who reads what.
Use it before a change. If legacyId is read by 14 subscribers, removing it will break 14 organizations. The change impact view shows the same thing while you edit.
Changelog
Each published API has a Changelog, made automatically from its endpoint history. Breaking entries are marked breaking. Subscribers see it on the API's page, next to its endpoints.
When you plan to remove an endpoint, deprecate it first and give subscribers a shutdown date. See deprecations and versions and releases.
What subscribers hear
Every subscribed organization's copy of the API follows the publisher's changes, and they're told:
Each person gets these the way their notifications say, and the organization's webhooks can pass them on.
Who sees what
Related
- SystemsCreate the apps and services you build or depend on, give them owners and tags, and find any system or API again.
- APIs and contractsDeclare what providers offer and what consumers expect. Rabbinatix pairs them into contracts and checks them field by field.
- Versions and releasesRun API versions side by side, read the history and diff of every endpoint, create releases with a suggested version, and check old copies.
- Retiring APIsRetire an API with a shutdown date and a replacement, and follow every consumer until they have all moved off.
- Change impact and Draft modeSee what an API change would break before anyone feels it, share the drafts for review, and publish them when they are right.
