Skip to main content

Design your first API

This walkthrough takes a project version from an empty canvas to a downloadable OpenAPI document. It uses the workspace; on an installation where the workspace is not yet on, the same steps apply on the classic canvases.

You need a project with a draft version. Create one in the main app (Create a project) — published versions are read-only everywhere in the Suite.

1. Open the version​

  1. On the main app, open the Designer dropdown and choose Workspace — or click Open canvas on the Suite home.
  2. In the top bar, pick the project and version. The left rail shows the version's domain folders; a new version has none, and everything sits in the unassigned bucket.
  3. Optional: create a domain folder — click the Domain chip, give it a name ("Billing") — so the canvas loads only that part of the catalog.

2. Add a class​

  1. In the left rail, click + ("Add a schema to this version"). Give it a name (Customer), a kind, a description and a domain.
  2. Select it. The inspector on the right opens its Class panel: name, description, folder, properties and tags.
  3. Under Properties, add id, email and createdAt. Each property has a name, description, Required, and a type: a primitive with a format, References another class, or List of these. Bind to a Type picks a registry type instead.
  4. Try Suggest properties — it asks the AI assistant for properties that fit the class, when an Ollama server is configured.

3. Add a path and an operation​

  1. Switch the lens toolbar to Paths (or Combined to keep the classes in view).
  2. In the left rail, click ＋ New path… and name it /customers; then ＋ New operation… and choose GET.
  3. Select the operation. Its inspector has Overview (summary, operation ID, the schemas it Consumes, security), Request (parameters and a request body) and Responses.
  4. Under Responses, Add response 200 and link it to Customer. In the Combined lens a solid edge now joins the operation to the class — that is the consumption edge.

4. Try it​

With the operation selected, click Try it (or Mock & preview in the toolbar). The console shows a request form — server, mock behaviour, scenario, auth, headers, body — and sends through the studio's relay. A draft version gets a synthesized preview; a published version with its hosted mock on answers for real. See Try it and mock.

5. Comment, search, lay out​

  • Hover a class card header, a property row or an operation lane and click the comment button to start a thread; @ mentions a tenant member. See Comments.
  • Press Ctrl / ⌘+K — Jump to anything… — to find a schema or path by name, or run an action such as Find every path that consumes Customer.
  • Auto-layout tidies the canvas; the layout is saved per domain, per user.

6. See the code​

Click Open as code in the toolbar. The code layer shows openapi.yaml in an editor with live Problems and Lint rails; edit it, then Apply to write the change back through a review step that classifies every change. Or open Code and exports from the top bar to pick another format — AsyncAPI, Arazzo, JSON Schema, GraphQL SDL or SQL DDL — and Download the OpenAPI document, validated against OpenAPI 3.2 before it leaves.

Next​

Cut and publish the version in the main app (Version and publish), then publish your first portal.