Skip to main content
Most work in the API Client starts from a request you send. API Design starts from the other end: you write the contract first, as an OpenAPI document, and everything else follows from it. The document lives in your project alongside your collections, so the design and the requests you send against it stay in one place. Open it from the API Design icon in the API Client sidebar.

​
Design a specification or build a collection?

Both describe the same API. They are good at different things. You are not choosing once. A specification can generate a collection you then send requests from, and a collection can be exported as an OpenAPI file. See sync a collection from a specification for the link between the two, and import an OpenAPI spec to bring an existing file in as either one.

​
What a specification is here

A specification is an OpenAPI 3.x document you edit as text, in YAML or JSON, with the editor helping you as you type: completion for OpenAPI keys, an outline of the document in the sidebar, a live documentation preview beside it, and problems flagged inline as you introduce them. You can author OpenAPI 3.1 (the default) and OpenAPI 3.0. Swagger 2.0 files can be imported, but only as a collection: they cannot be edited as a specification. There is no AsyncAPI authoring.
Requestly stores the standard document and nothing else. There are no Requestly-only keys added to your file, so what you export is what you wrote.

​
How specifications sit in a project

Everything under API Design is scoped to one project.
  • Specs are the documents themselves. A project can hold as many as you like.
  • The Components Library is a single shared library per project. Every specification in the project can reference the same schema, parameter, or response instead of repeating it. See the Component Library.
In a local project, both are ordinary files you can commit: specifications under specs/, library entries under components/<category>/. In a team project they sync like the rest of your project, and your role applies. On a read-only role you can open and read every specification and component, but Save, rename, and delete are disabled with the reason on hover.

​
The sidebar

The panel has two sections, a search box across the top, and a + button on each section header.
  • Specs lists every specification in the project. Expand one and you get its outline: Servers, Tags, Paths, Components, and Security. Paths expand into their operations, each with its method badge. Clicking an outline row jumps the editor to that line.
  • Components Library lists the project’s reusable pieces, grouped by category. It starts collapsed, because most of the time you are working in a document rather than browsing the library. Click the header to open it.
Typing in the search box filters both trees at once and opens both sections while the query is active, so a match in the library is never hidden behind a collapsed header.
With more than one project active, the panel shows one collapsible section per project, each with its own Specs and Components Library.

​
Create your first specification

1

Open the Specs section

Click the API Design icon in the API Client sidebar. If the project has no specifications yet, the Specs section shows “No specs yet” with a New spec button.
2

Pick an OpenAPI version

Click New spec (or the + on the Specs header) and choose OpenAPI 3.1 (default) or OpenAPI 3.0. The same choice is available from + New → API spec in the sidebar toolbar.
3

Name it

The specification opens in a new tab as a draft, seeded with a minimal valid document, and the name in the breadcrumb is focused. Type a name and press Enter.
4

Save

Press Cmd/Ctrl + S or click Save. Nothing is written to the project until you save, so a draft you abandon leaves nothing behind.
Next: create and edit a specification covers the editor itself.

​
What you can do with a specification

Once a specification exists, the rest of API Design hangs off it.
  • Read it as documentation. The rail beside the editor renders the document as you type: operations, parameters, request and response bodies, and schema trees.
  • Keep it clean. Problems are flagged inline in the editor and collected in an Issues panel, with a governance ruleset you can tune per project. See issues and governance.
  • Turn it into requests. Generate a collection from the specification and keep the two in step as the document changes. See sync a collection from a specification.
  • Cut a version. Freeze the current document as a named release you can come back to. See versions and releases.
Deleting a component that specifications still reference breaks those references. Requestly warns you before the delete and then flags every broken $ref in the affected documents.