ENDPOINTS

The whole API surface, on one page

REST routes, GraphQL operations and the events you publish, grouped by resource. Each one shows its method, auth, parameters, status codes and the types it takes and returns, and it links to the database tables it reads or writes.

Open the Relay API Make your own

> map the API

wrote api.endpoints.json · api.endpoints.html

# what the skill ran for you

$ vibex import openapi openapi.json docs/api.endpoints.json

$ vibex render docs/api.endpoints.json --open

REST and GraphQL, side by side

The Relay API mixes REST calls with the events that handheld scanners push, and every route is linked to its tables. The merchant portal is GraphQL, so its queries, mutations and subscriptions come with the object types behind them.

relay.endpoints.html · 17 endpoints · 5 groups · every one linked to its tablesFull screen ↗

Click an endpoint for its parameters, and click its request or response type to jump to that type. The tables it touches are highlighted and listed.

What it draws

Every field in the spec, and where it shows up. An endpoint needs an id, a method and a path. Everything else is drawn when it is there.

ENDPOINTS

method: A coloured badge. One catalogue can mix all three kinds.
GETPOSTPUTPATCHDELETEHEADOPTIONS
QUERYMUTATIONSUBSCRIPTION
EVENT
path: REST: /users/{id}. GraphQL: the signature, shipment(id: ID!). Event: the topic, queue or webhook name.
summary · description: One line on the row, and the longer text in the details panel.
auth: A 🔒 chip with the scheme or role (bearer, api-key, admin). none draws nothing, so an open route stands out by its missing lock.
status[]: Status codes as a chip on the row, up to four.
params[]: A table in the details panel: name, where it goes, type, and whether it is required.
pathqueryheaderargbody
request · response: Type names. When the type is in the catalogue, it becomes a chip that jumps to it.
entities[]: ERD table IDs this endpoint reads or writes. They are highlighted on selection, and the dashboard lists them per table.
deprecated · tags: A deprecated endpoint is struck through and chipped. Tags are free labels, and search matches them.
sources[]: The handler's file and line, linked to the code when meta.repository is set.

GROUPS AND TYPES

groups[]: One card per resource, tag or controller. An endpoint with no group goes in default.
types[]: The schemas the endpoints reference, each with its fields and a required mark.
objectinputenuminterfaceunionscalar
meta.api_kind · base_url · version: rest, graphql or mixed, plus the server URL and API version in the header.
layout.columns · card_width · show_types: Group cards are laid out as masonry, in one to four columns. show_types: false hides the types section.

Where it reads from

$ vibex import openapi openapi.json docs/api.endpoints.json

# every schema, not only the ones an operation references

$ vibex import openapi openapi.json docs/api.endpoints.json --all-types

Works with OpenAPI 3 and Swagger 2. An operation's first tag becomes its group, with the tag's description, and any further tags stay as tags. security becomes auth, and an empty requirement becomes none. Numeric response codes become status, and $ref parameters and bodies are resolved. The base URL comes from servers[0], or from host and basePath in Swagger 2.

A YAML document needs the optional yaml package. Run npm install in the skill folder, or convert the document to JSON.

$ vibex import graphql schema.graphql docs/portal.endpoints.json

Query, Mutation and Subscription each become a group, and every field on them becomes an operation with its argument signature. Object, input, enum, interface and union types fill the types section. The parser is vibeX's own. It skips directives and whatever else it does not understand rather than failing on it. Add --erd to draw the same file as an ERD instead.

> catalogue the controllers

wrote api.endpoints.json · api.endpoints.html

The skill reads @Controller prefixes and @Get/@Post/… paths, including the global prefix and URI versioning. @UseGuards and @Roles become auth, and the @Body() DTO becomes request. @Param, @Query and @Headers become params, and a query DTO is expanded into one param per property. GraphQL resolvers map @Query, @Mutation and @Subscription the same way. Each endpoint points at its handler.

Check this one before you trust it. It is the agent's reading of your code, not an import.

> list every route in the server

wrote api.endpoints.json · api.endpoints.html

The skill reads router.get('/x', …), app.post(…) and fastify.route({ method, url }). Topics you publish to go in as EVENT, so the catalogue covers what the service emits as well as what it answers.

Same caveat. Read the draft once.

The spec you keep

{
  "schema_version": 1,
  "diagram_type": "endpoints",
  "meta": { "title": "Orders API", "base_url": "/v1" },
  "groups": [{ "id": "orders", "label": "Orders" }],
  "endpoints": [
    { "id": "create", "group": "orders",
      "method": "POST", "path": "/orders",
      "summary": "Place an order",
      "auth": "bearer", "request": "CreateOrder",
      "response": "Order", "status": [201, 400, 409],
      "entities": ["order", "customer"] },
    { "id": "placed", "group": "orders",
      "method": "EVENT", "path": "order.placed",
      "summary": "Published after the order commits",
      "entities": ["order"] }
  ]
}

entities holds IDs from your ERD. That list is what lets the dashboard answer “which routes write the orders table?”

Keep summary to one line. A long description goes in description, which appears in the details panel.

The full contract is schemas/endpoints.schema.json.

What validate stops

$ vibex validate docs/orders.endpoints.json

error dangling-ref endpoints[2].group "payments" is not a group id (known ids: orders)

warning duplicate-route GET /orders appears more than once

warning summary endpoints[1] (GET /orders) has no summary

1 error(s), 2 warning(s)

Errors

Exit 1. Each one names the field.

dangling-refan endpoint's group does not exist
id-clashan endpoint, group or type sharing an ID
missingan endpoint with no path, a type with no name
typestatus that is not a list of codes, entities that is not a list of IDs

Warnings

Printed, never blocking.

duplicate-routethe same method and path listed twice
summaryan endpoint with no summary
sizemore than 80 endpoints. One catalogue per bounded context

The sentences it writes

A docs section can ask for endpoints.operations and endpoints.types. From the Relay build, word for word:

POST /v1/shipments — Book a shipment and mint a tracking number per parcel. It accepts CreateShipmentInput. It returns Shipment.endpoints.operations · relay.endpoints

GET /v1/shipments — List the calling merchant's shipments, newest first. It returns Shipment[].endpoints.operations · relay.endpoints

Your summary is attached as written, never reworded.

What it connects to

ERD

Routes and the tables they touch

The dashboard overview has a table: every ERD table, and the endpoints that list it. Each one opens its panel with that row selected.

ERD →

From a container to its routes

A container's link can open its catalogue, the way Relay's shipment API does.

C4 →

INTAKE

“This route is missing”

Every endpoint's details panel has a report link that opens an issue already naming it.

Intake →