Map your systems
Document your APIs
Say what each API is for, what every field means and when each answer happens, and let Rabbinatix keep the docs honest: who relies on each field, the flows it is part of, and why it is like this.
Open API catalog in the appWhy write it down
An API outlives the memory of the people who built it. Months later nobody remembers what flag means, whether total is in cents, or when the API answers 409. Rabbinatix keeps that knowledge next to the API itself, and shows it wherever the API appears: the API reference, a broken contract, the generated code and search.
Docs never change a contract. Writing a meaning, an example or a "when" line is never a mismatch, never breaks anyone, and shows in the history as a docs change.
Write the docs in the endpoint editor
From a system's APIs tab an API opens on its own page; from the map, search or the API catalog it opens in a side drawer. Either way a saved API opens read only: everything it says, laid out to read, with copy buttons on the path, the names and values, the bodies and a ready-made Copy as cURL command. Press Edit to change it; Cancel on the page (or Back to view in the drawer) leaves the form without saving.
- Under Basics, Summary says in one line what the API is for. Details says the rest: what it does, what it changes, who may call it and what to watch out for. Details take Markdown: bold, lists,
codeand links. Press Preview to see them. - A provider also has Why it is like this: a short note on a decision, such as "returns 202 because refunds run in the background".
- In a body, put a field's meaning at the end of its line after
#, and an example after=:
total: integer = 1299 # Order total in cents, tax included
currency: string = "EUR" # ISO 4217 code- Every header, query and path parameter has a Meaning and an Example box under it.
- Each response has When it happens, such as "The order belongs to another customer" for a
404. - Open Example under a body to keep one whole example. Fill from the shape starts from made-up values, and Rabbinatix tells you straight away when the example doesn't match the shape.
When you save, the box next to Save changes asks why it changed. Your answer shows in the API's history.
The API reference
Every API has a reference page that everyone in the workspace can read. Click an API on a system's APIs tab, or switch that tab to Reference to read all of them.
- Each field, parameter and header shows its type, whether it is required, its meaning, its example and Used by: the systems that send it or read it. A field nobody reads says so, which makes it safe to change.
- Part of lists the flows that call the API and at which step.
- When a test run of a scenario called the API, the page shows that real request and answer instead of made-up values.
- Try it sends a request to the API's logic in the simulator, or shows what its test server answers when no logic implements it yet. Nothing real is called.
- Why it is like this shows the decision note, how the API changed and why, and everything linked to it: tickets, whiteboards, requirements and chat.
- Its tabs: Overview (all of the above), Consumers (who calls it and which fields they use), History (every revision; restoring one opens it in the form to save as the next) and Test server.
- Edit turns the overview into the form, on the same page; Save changes or Cancel at its bottom brings the page back. The link icon copies a link to the page, and … has Fill the docs with AI, Compare with consumers and Deprecate…. … also has Delete…. Opened from the map, search or the catalog, an API opens in a side drawer.
People who may edit APIs fill the docs in place: point at a row (or move to it with the keyboard) for Write the meaning and Ask about this field.
Docs hints and the score
The side of the reference shows Documented: how many of the API's fields, parameters, error answers and its summary have docs. Below it, one line names the fields that have no meaning yet, the ones most systems rely on first; Write them, most relied-on first opens the first one's meaning box. The other hints list what else is missing, and names that don't say what they hold, such as data or obj.
Hints about the path, such as a verb in it (/getUsers), offer See who it breaks. That opens the editor with the new name, so you see the impact before anything is saved. Add it under the new path creates the API there, so you can deprecate the old path and let callers move over. See Deprecations.
Let Rabbinatix help
- Suggestions: an empty meaning shows a suggestion when the same field is explained elsewhere: in the field glossary, in other APIs, or by a system that calls this one. Press Use.
- The field glossary: define a field once, and every API with a field of that name shows the meaning.
customer_idandcustomerIdcount as the same name. - Your AI assistant: … → Fill the docs with AI copies a prompt for your own assistant. Paste its reply, untick what is wrong, and save. Only empty docs are filled.
- Ask about this field: a question goes to a chat room with a link to the field. When someone answers, Save as the meaning turns the answer into the field's docs.
Docs everywhere else
- Import and export: OpenAPI descriptions, examples and response descriptions come in and go back out. Postman descriptions and saved examples come in too. Importing a spec again keeps the meanings you wrote here wherever the spec has none. See Import and export.
- Search: the API catalog finds APIs by what their fields mean, and links straight to the field.
- Contracts: open a broken field in a contract to read what it means.
- Generated code: meanings become doc comments in TypeScript, Python, C#, Java, Go, Kotlin, Swift, Dart, PHP, Ruby and Rust.
- Test servers: examples are what the test server answers, before any made-up values.
Related
- APIs and contractsDeclare what providers offer and what consumers expect. Rabbinatix pairs them into contracts and checks them field by field.
- Import and exportBring in OpenAPI, Postman, Pact and browser recording (HAR) files, sync again when they change, and export OpenAPI and Pact.
- 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.
- AI assistant referenceConnect the assistant in your editor, review its drafts, and the guide it reads.
