# API Specifications The OpenAPI editor in Frends is used to define the API specification that API Management uses for routing, documentation, and Process linking. In practice, this means you describe your API with an OpenAPI document, save it in Frends, and then connect each operation either to a Process through an API Trigger or to a passthrough configuration. ## OpenAPI editor in Frends In Frends, APIs are created and maintained in **API Management**. The editor stores an OpenAPI definition that Frends uses as the API contract for the selected API. Current Frends version primarily supports OpenAPI `3.0.4`, with OpenAPI `2.0` available for legacy use. The latest supported version of OpenAPI is the default OpenAPI version in a new API document. The API definition is then deployed to Agent Groups, where incoming HTTP requests are matched against the saved API operations. The editor is not the runtime implementation itself. Instead, it is the definition layer for the API. Each operation in the specification is later fulfilled either by a linked Process or by passthrough configuration. This is an important distinction when reading the specification inside Frends: the document defines what the API looks like, while runtime behavior is completed by API Triggers, Process logic, Return shapes, API Policies, and deployment configuration.

API editor in Frends uses OpenAPI specification and Swagger UI.

### How the editor is used The OpenAPI editor is available through **API Management** in the Development Environment and Agent Group. When you create a new API, you provide the OpenAPI definition in the editor and save the API. Frends then reads that document and uses them to present the API in the management view and to build the operation structure that can be linked to Processes. The saved API can then be deployed to other Agent Groups. The same definition can be active in multiple Agent Groups, with the final callable address depending on the Agent Group base URL and the API `server URL` defined in the specification. ## How Frends uses the OpenAPI document An OpenAPI document is a JSON or YAML document that contains the API description, including metadata, server information, paths, operations, parameters, request bodies, responses, reusable components, and security definitions. In OpenAPI `3.0.4`, the top-level `openapi` field identifies the specification version used by the document, while objects such as `info`, `servers`, `paths`, and `components` describe the API structure. In Frends, the OpenAPI document is used as the source for API metadata and operation definitions. Frends explicitly reads the API title, description, version, server URL, and paths from the document. These values are then shown in the API list, API details, and operation structure inside **API Management**. ### Top-level document version The OpenAPI field `openapi` defines which version of the OpenAPI Specification the document follows. In the OpenAPI specification, this field is required and is used by tooling to interpret the document correctly. It is not the same as `info.version`, which describes the version of the API itself. In Frends, this field determines how the document is interpreted as an OpenAPI document. ### API metadata The OpenAPI `info` object contains metadata about the API. In the specification, this object describes general API information such as title, description, and version. In Frends, the `info` object is used mainly for displayed API metadata. The `title` becomes the displayed API name. The `description` becomes the displayed API description. The `version` is read from the specification, but the versioning lifecycle of the API in Frends is not controlled manually only through this field. Frends manages API versions automatically when the definition is saved and when the API is deployed. #### `info.title` In OpenAPI, `info.title` is the title of the API. In Frends, this is shown as the API name in the API list and details panel. #### `info.description` In OpenAPI, `info.description` is descriptive text for the API. In Frends, this is displayed as the API description in the API list and details panel. #### `info.version` In OpenAPI, `info.version` is the version of the API description. In Frends, versioning has additional platform behavior. Frends follows semantic versioning in the form `major.minor.patch`, but API versions are managed automatically by lifecycle events. Each saved change to the API specification increments the patch version, and each deployment increments the major version. Published versions are immutable after deployment. This is one of the clearest places where Frends behavior differs from standard OpenAPI usage. ### Server definitions The OpenAPI `servers` field defines one or more Server Objects that describe where the API is served. In the OpenAPI specification, this is connectivity information, and if the field is omitted, the default server URL is `/`. A Server Object contains a `url` field and may include a description and variables. In Frends, the `server URL` is used as the base path of the API. This path is appended after the Agent Group base URL. Frends requires the `server URL` to begin with `/api/`, and it must be unique within the Agent Group. This constraint is specific to Frends and is one of the few places where the platform adds stricter behavior on top of standard OpenAPI. #### `servers[].url` In standard OpenAPI, the server URL identifies the server address or relative base URL for the API. In Frends, this field acts as the API base path and is central to routing. The actual full callable URL is formed by combining the Agent Group base URL with the API server URL and then the selected operation path. #### Multiple server definitions OpenAPI allows multiple server definitions within the API document. Frends uses the main `server URL` as the single base path used in API Management. If your design includes several server entries, Frends uses the first one as the base path for this API and the rest are ignored functionality-wise, but are visible in API specification UI for documentational purposes. #### Server path overrides OpenAPI allows defining new server entries for each path, overriding the main server definition for that path. As Frends only uses the first, main server URL entry to define the API paths, these overrides do not raise an error within the API editor in Frends. But the overrides are also disregarded similarly to the additional main server entries and do not cause any changes in the API functionality. ## Paths and operations The OpenAPI `paths` object contains the relative paths for the API endpoints. Each path item can define one or more operations such as `get`, `post`, `put`, or `delete`, and OpenAPI requires path template variables to correspond to declared path parameters. In Frends, the `paths` section defines the available API endpoints that can be linked to Processes or passthrough configurations. The `server URL` defines the base path, and the entries under `paths` extend that base path with operation-specific routes. This means the paths in the specification directly define what operations appear in **API Management** and what can later be connected to implementation logic. ### Operation structure in Frends Each operation in the specification becomes a routable API operation in Frends. When a request reaches the Agent, Frends matches the incoming HTTP method and path to the correct operation. If that operation is linked to a Process through API Trigger, the request starts the linked Process. If it is configured as passthrough, the request is forwarded to the configured backend target instead. This is another practical difference from a generic OpenAPI editor. In Frends, operations are not only documentation entries. They are deployable runtime routes that are expected to be fulfilled by platform configuration. \[Image placeholder: API details panel showing operations under a selected API, with visual indication of whether each operation is linked to a Process or configured as passthrough.] ### Path parameters, query parameters, headers, and body OpenAPI defines parameters and request bodies as part of the operation contract. Parameters can be located in places such as `path`, `query`, `header`, or `cookie`, and request content is defined through the `requestBody` object. In Frends, these definitions are especially important when an operation is linked to a Process. The API Trigger exposes incoming request data, including path parameters, query parameters, headers, and body, as variables that the Process can use directly. This means the specification is not only descriptive. It also shapes what request data the Process receives through the Trigger. Note that the parameter definitions are not binding. While the defined parameters are exposed as variables within the linked Process, the request may contain additional parameters and lack some defined parameters. The additional parameters are accessible within Processes through square bracket selectors `[ ]` for corresponding parameter type, and missing parameters will be provided as `null` value in the variables. ## Linking operations to Processes In Frends, a Process is connected to an API operation through an **API Trigger**. A Process linked to an API endpoint must have exactly one API Trigger, and one Process cannot be linked to multiple API endpoints at the same time. If the same integration logic is needed across several endpoints, that logic should be moved to a Subprocess and reused from endpoint-specific Processes. This Process linkage is outside the OpenAPI specification itself, but it is central to how the editor works in Frends. The specification defines the operations, and the API Trigger connects those operations to executable Process logic. ### Request handling through the API Trigger When an operation is linked to a Process, the API Trigger provides request data such as path parameters, query parameters, headers, and body as Trigger variables. The linked Process then uses those values to implement the API behavior. The response is returned through a **Return** shape that matches one of the responses defined in the OpenAPI document. The API Trigger configuration also includes Frends-specific runtime options such as allowed protocols, CORS settings, whether the endpoint is private, and whether Trigger parameters should be omitted from Process Instance logs. These are runtime concerns and are not part of the OpenAPI editor itself, but they are directly related to how operations defined in the editor are executed in Frends. ### Specification-driven response handling OpenAPI defines responses through the Response Object, where each response has a status code, description, and optional content definition. In Frends, the Return shape used by the linked Process is expected to match the response definitions in the API specification. This makes the OpenAPI document the contract that the Process implementation is expected to follow. Do note though, similarly to the incoming parameters being not binding, the Return object may contain more or less fields and different statuses than what is defined in API specification. While this does not cause errors in validation or operation for the Process, it is not recommended to diverge from the API definition to stay true to the published API specification. ## Components and reusable definitions The OpenAPI `components` object holds reusable objects such as schemas, responses, parameters, request bodies, headers, security schemes, links, and callbacks. In the OpenAPI specification, objects inside `components` have no effect unless they are referenced from elsewhere in the document. In Frends, `components` are supported as part of the OpenAPI definition, and they behave primarily as standard OpenAPI structures inside the specification. ### Schemas and reusable request or response parts Schemas, reusable parameters, reusable request bodies, and reusable responses are part of standard OpenAPI modeling and can be used in the document in the usual way. Frends uses the resulting operation contract for API structure, request handling, and response expectations. ### `securitySchemes` as the main exception The most important special case inside `components` is `securitySchemes`. OpenAPI defines Security Scheme Objects to describe supported authentication mechanisms, and operations can refer to them through security requirements. In Frends, `securitySchemes` are supported mainly for documentation purposes. The effective runtime security is controlled by **API Policies**, not by the OpenAPI definition itself. This means that even if security schemes are declared in the specification, authentication, throttling, and access control are applied through API Policy configuration. Frends documentation notes that advanced settings such as an OAuth authorization URL may still belong in the specification, but runtime enforcement is handled elsewhere. This separation is one of the most important Frends-specific differences to understand when using the OpenAPI editor. The specification describes the API contract, but API access control is configured independently so that security can be updated without modifying the OpenAPI definition or redeploying the API. ## Security behavior in Frends OpenAPI allows security requirements to be defined at the top level or at operation level. The specification also allows multiple possible security options and operation-level overrides. In Frends, API security is managed through **API Policies**. These policies support API keys, OAuth bearer tokens, and private application tokens, and they can target individual operations or use wider matching patterns. Because policies are managed separately from the API definition, security behavior can be changed without editing the specification in the OpenAPI editor. ### What to use in the editor and what to configure elsewhere Use the OpenAPI editor to describe the intended API contract, including documented security scheme details where needed. Use **API Policies** to define who can call the API, how callers authenticate, and what runtime controls apply. This split is intentional in Frends and is a key reason why the `securitySchemes` section behaves differently from what some users may expect from a standalone OpenAPI tool. ## API Specification UI and testing After an API is deployed, Frends can expose an interactive API Specification UI for testing the API against the deployed definition. This UI presents the API structure based on the OpenAPI document and allows trying out operations against the deployed endpoint. Access to this UI is separate from access to the API itself, and it can also be secured using API Policy configuration. This UI is an important part of how the OpenAPI editor is used in practice. The editor defines the contract, deployment publishes that contract, and the specification UI makes the deployed contract visible and testable in a browser. \[Image placeholder: API Specification UI opened for a deployed API, showing operation list, parameter input fields, and the Try it out and Execute actions.] ## Passthrough APIs and the OpenAPI editor In Frends, an operation defined in the OpenAPI document does not have to start a Process. It can also be fulfilled by passthrough configuration. In that case, Frends acts as the public API entry point and forwards the request to another backend API without executing Process logic. This is configured separately from the OpenAPI document, but the operation still comes from the API definition created in the editor. The specification therefore continues to define the public contract, while passthrough defines how the request is technically fulfilled. ## Field Reference Most fields in the OpenAPI editor behave as standard OpenAPI fields. Only a few have special functionality in Frends. ### `openapi` Defines the OpenAPI Specification version of the document. In Frends, this controls how the document is interpreted as an OpenAPI definition. It is not the deployed API lifecycle version shown in Frends. ### `info` Contains the API metadata shown in Frends. The most visible fields are `title`, `description`, and `version`. ### `info.version` This field participates in displayed API metadata, but Frends also manages API lifecycle versions automatically. Saving the definition increments the patch version, and deploying increments the major version. Published versions are immutable. ### `servers` Defines the API base path. In Frends, the `url` under `servers` is especially important because it becomes the API base path and must follow Frends rules such as starting with `/api/`. ### `servers[].url` This field is used as the API base path in Frends. It must start with `/api/`, and it must be unique within the Agent Group. The final callable URL also depends on the Agent Group base URL, which specifies the domain, subdomain and port of the URL. Only the first URL specifies the working base path of the API. ### `paths` In Frends, the paths define the operation routes that can be linked to Processes or configured as passthrough. ### `parameters` Defines request parameters such as path, query, and header values. In Frends, these feed into API Trigger request data for linked Processes. ### `requestBody` Defines the request payload contract. In Frends, the incoming body is made available to the linked Process through the API Trigger. ### `responses` Defines the response contract for each operation. In Frends, the linked Process should return a response that matches one of these definitions through the Return shape. ### `components` Defines reusable OpenAPI objects. In Frends, these are primarily standard OpenAPI structures, with `securitySchemes` being the most notable case with separate runtime behavior through API Policies. ### `components.securitySchemes` and `security` Define documented security requirements and supported mechanisms in the OpenAPI document. These fields are mainly descriptive in Frends. Effective runtime authentication and access control come from API Policies rather than from the OpenAPI definition. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.frends.com/reference/api-management/api-specifications.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.