Contract Graph
Put many services on one map, read what the findings mean, and share or move a workspace. Needs an account.
Contract Graph puts many services on one map. It shows entities that more than one service exposes, endpoints that duplicate each other, one idea stored under several field names, and which services depend on which. It lives at /graph and needs you to be signed in. Accounts and privacy explains what that means on your site.
A set of services is called a workspace. One workspace holds up to 60 services.
Adding services
Click Add Service in the sidebar. There are four ways in:
| Method | How | Notes |
|---|---|---|
| Files | Drop files on the box, or anywhere on the page | OpenAPI, Swagger, Postman or WSDL, as .json, .yaml, .yml, .wsdl or .xml. Several at once is fine |
| URL | Paste an address and click Fetch | Your browser fetches it directly. Many servers block that, and the page will say so |
| Paste | Open Paste a specification, optionally name the service, then click Add pasted spec | Same formats as files |
| Sample | Try the sample estate | Loads "Northwind (sample)", a made-up set of services to look around in |
You can also send the specification open in the API Map with its Add to Contract Graph button.
A WSDL is read as a proposed REST design and then treated like any other service. A file with no operations and no schemas is turned away, with a message asking whether it is an API specification at all.
The views
Once a workspace has services, five tabs appear across the top. They need a wide window, and are hidden on narrow screens.
| Tab | What it shows |
|---|---|
| Map | Services as nodes, joined by the relationships found between them |
| Entities | Entities exposed by more than one service, and where their shapes disagree |
| Duplicates | Endpoints that duplicate or nearly duplicate each other across services |
| Concepts | Fields that mean the same thing under different names |
| Findings | Everything above in one list, by severity |
On the Map tab you can switch between Graph, List and Table. The Layouts menu offers Force, Ring and Grid, plus Reset positions. Drag a node to move it, and the position is remembered in this browser. Zoom runs from 30% to 200%, and Fit brings everything back into view.
The lines between services come in three kinds:
- calls, drawn solid: one service sends requests to a path the other one serves.
- references, dashed: a field such as
customerIdpoints at a resource another service owns. - shares, dotted: both services expose the same entity.
Click a line to see How this was found and the Evidence for it. Click a service to open its panel, with tabs for Overview, Operations, Entities and Relationships. The Overview says which services it depends on, which use it, and how many more would feel a change to it indirectly.
Reading the findings
| Finding | Severity | What triggered it |
|---|---|---|
| An entity whose shape differs between services | High | A field exists on one side only, or the types conflict. Required versus optional alone does not count |
| A duplicate endpoint | High | The same method and the same path shape in two services |
| A near-duplicate endpoint | Medium | The same method and resource, with at least half the response fields in common |
| One concept under several names | Medium, or High if the types differ too | For example customerId in one service and custNo in another |
| A service with no authentication | Medium | No operation in it declares any auth |
| A service that shares nothing | Info | It has no relationship to any other service in the workspace |
Version segments such as /v1, and words like api or public, are ignored when paths are compared. customerId and customer_id count as the same name. Postman collections are left out of the duplicate check.
When a service declares no schemas, which is common for Postman collections, its entities are guessed from its example responses. Those are labelled "partly inferred from examples". Treat them as a lead to check, not as fact.
Sharing and export
The Share menu has:
- Copy share link. The link carries the workspace itself, after the
#, so no server receives it. It can't be longer than 16,000 characters, and a larger workspace asks you to download the file instead. - Copy embed code, an iframe for a wiki or a dashboard.
- Download PNG and Download SVG, from the Graph view.
- Copy as Mermaid, to paste the diagram into Markdown.
- Download workspace file, a
.contract-graph.jsonthat someone else loads with Import workspace file.
Whoever opens a share link sees the workspace marked "Shared", and can keep a copy with Save to my workspaces. If they have to sign in first, the link is kept through the sign-in, unless they sign in with Google or GitHub. In that case, open the link again afterwards.
Where workspaces are kept
In this browser. Workspaces are filed under your account, so two people signed in on the same computer each see their own. They do not follow you to another browser or device, even with a connected account. To move a workspace, download its file and import it on the other side.
If you mapped services before signing in, they move into your account when you sign in.
Ask AI sends your question and details of the workspace to the AI service your site has configured. It is the one part of Contract Graph that sends anything out of the browser, and only when you use it.