API Specifications

API Editor and OpenAPI specification details in Frends.

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 supports OpenAPI 3.1.1 and any 3.0.x versions, 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 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.