Chapter 10 of 10
What to Look for in an API Design Tool
Eight criteria that decide whether a design tool still helps in a year, written as questions to ask rather than as a list of vendors.
Comparison articles about design tools usually list products and score them on features. This chapter names the criteria that still matter after the trial, as questions you can put to any tool including the one you already use.
The criteria, and why each one is on the list
1. What is the stored artefact
Ask whether the tool stores the contract itself or stores something else and can produce a contract on request.
The difference decides what happens to everything downstream. When the description is the artefact, the reference documentation, the mock and the tests are projections of one thing. When the description is an export, every consumer of it is working from a copy, and a copy has a date on it.
2. Can reuse cross a project boundary
Reuse inside one description is the easy half, and most tools handle it because the format does.
The harder question is what happens when twelve services should answer with the same error body. Ask whether a definition can live above the individual API, whether a consumer records which version of it they took, and whether an update reaches them automatically or on their own schedule. Both answers are defensible, and a tool that has not thought about it leaves you copying.
3. Where does a rule check appear
A convention that is checked in a nightly report is a list, and a convention checked while somebody types is a correction.
Ask where violations surface, whether they can be fixed from where they appear, and whether severity is something you set rather than something the vendor decided. Then ask the one that matters most, which is whether a rule can block a release and whether that blocking is optional. A tool with only advisory checks never changes behaviour, and one with only blocking checks gets switched off.
4. Can you express your own conventions
Every organisation has rules the built-in set does not cover.
Ask what a custom rule can target and what it can match, because that boundary is where you will find out whether your house style is expressible. A tool that only offers regular expressions over a name will not carry a rule about response coverage, and knowing that before you buy is better than discovering it during rollout.
5. What does it tell you before a change ships
The design question that recurs is not what the API looks like, it is what this edit does to the people already using it.
Ask whether the tool can diff two versions, whether it classifies a change as breaking, and whether that classification appears before publication rather than after. The versioning guide covers what should count as breaking, and a tool that has no opinion leaves that judgement to whoever is reviewing at the time.
6. Can more than one person work at once
A single-file description in a repository handles concurrent work through the mechanism the repository already has, which is branching and merging.
A tool that owns the description has to provide an equivalent. So ask what happens when two people edit the same specification, and what happens when one of them needs a fortnight on a change that should not reach the published version yet. Ask what conflict resolution looks like, because the honest answers vary widely.
7. What can you take with you
Ask what a full export contains and try it on the largest description you have.
A round trip is the test. Import, export, and diff the result against the original, since what disappears is what the tool does not really model. Comments, examples, extensions and vendor specific fields are the usual casualties, and each one is a thing you would have to rebuild elsewhere.
8. Does it cover the decisions or only the syntax
An editor that validates a document tells you the file is legal. Every chapter in this guide is about a decision the file cannot be wrong about.
So ask what the tool does about the choices rather than the syntax. Whether it can hold a house convention, whether it can make the agreed error shape the easiest one to use, and whether it notices when a list endpoint ships without pagination. That is the difference between a tool that stores your design and one that participates in it.
A scorecard you can use
| Criterion | The question | Poor answer |
|---|---|---|
| Stored artefact | Is the contract the thing, or an export | A contract generated on demand from something else |
| Reuse across projects | Can one definition serve several APIs | Copy and paste, with no record of the source |
| Where checks appear | Do violations show while editing | A report you have to go and read |
| Custom conventions | What can a rule target and match | A fixed rule set with no extension |
| Change impact | Is a breaking change named before release | A diff of raw text |
| Concurrent work | What happens when two people edit | Last write wins |
| Export | What survives a round trip | An export missing examples and extensions |
| Decisions | Does it hold conventions, not just syntax | Validation only |
How to actually evaluate
Do not evaluate on a sample specification, because sample specifications are consistent and yours is not.
Import your largest real description and look at what arrived. Then break one of your own conventions deliberately, such as adding a list endpoint with no paging parameters or an operation with no error response, and see whether anything says so and where. Finally export and diff against what you imported.
Three afternoons of that will tell you more than a feature matrix, and it surfaces the round trip problems that are expensive to discover later.
In Routebase
Routebase answers these criteria in a specific way, and the previous chapters are where each answer is described in full.
The stored artefact is the specification, and the reference documentation, the mock server, the contract tests and the monitors are derived from it rather than maintained beside it. Reuse works at two levels, with components inside a specification and an organisation-level shared library above it, where a linked definition records the version it took and an update is accepted rather than imposed. Conventions are style guide rules with severities set per organisation and overridable per project. They surface in an issues panel with one-click fixes while you edit and again in the publish dialog, and blocking on publish is a switch you turn on when you are ready. Custom rules extend that to endpoints, schemas and specification metadata. Versions can be compared, breaking changes are named before a release, branches exist for work that should not reach the published version yet, and every frozen version exports as YAML, JSON, Postman or Insomnia.
The Style Guide, Shared Library, Branching and Import and Export guides cover the four in the product documentation, and the API design feature page has the short version.
Frequently asked questions
What should you look for in an API design tool?
Ask what the tool stores, whether it can express reuse across more than one API, where its rule checks appear, and what you can take with you if you leave. Those four separate an editor from a design workflow. The features that demo well, such as a pretty rendering of the document, tend to matter only on the first afternoon.
Do you need a design tool if you can write OpenAPI by hand?
Not for one small API maintained by one person, where a text editor and a linter cover it. The case for a tool starts when several people edit the same description, when shapes have to be reused across projects, or when conventions have to hold without a reviewer noticing every deviation. Those are coordination problems rather than editing problems.
Is a design tool the same as an API client?
They overlap on sending a request and diverge everywhere else. A client is organised around a collection of saved requests, while a design tool is organised around a contract that other artefacts are derived from. The distinction shows up when you ask what happens to the mocks, the tests and the documentation when the contract changes.
How do you evaluate an API design tool properly?
Import your largest real specification rather than a sample, then make a change that should be caught by one of your own conventions and see whether anything says so. Then export the result and diff it against what you imported. What survives the round trip, and what the tool noticed, tell you more than any feature list.
Last reviewed by The Routebase Team.