Frends supports importing and editing Swagger Specifications. Swagger Specifications can be used to generate Processes that serves as API endpoints. Processes that belong to a Specification can be managed and deployed as a unit.

The API Management page can be found under "API". 

Frends support importing Swagger 2.0 Specification in JSON format. YAML mark up is not supported. If your Swagger Specification is in YAML, use for example the Online Swagger Editor to download a converted version. This tool can also be used for creating Swagger Specifications that can be imported into Frends. 

It's possible to modify an imported Swagger Specification using external tools. If you want to update an imported Swagger Specification, just import the updated specification and Frends will automatically create a new version of the Specification. Note that the one thing that can not change in between imports is the base path of the Specification - if the base path differ, a new API will be created rather than a new version of the old API. 

API versions exists in two different states. The version that is seen in the Development Environment is always the current Development version of an API. In all other Environments, published versions are shown.

A development version of an API is a version where the linked Processes does not have locked down versions. That means that the user can update any Process that is a part of the API without taking any additional actions. The development version can also have it's Swagger specification modified. When an API is ready for deployment, a Published version will be created. 

A published version contains everything a development version does, but it no longer allows any changes. It locks down the Process versions which is in use, and the Swagger Specification can no longer be changed. A published version can be deployed as a unit, and it can also be used to rollback the Development version to a previous point. 

When deploying the user can choose to deploy a previously Published version, or create a new Published version from the current Development version. The Deployment dialog allows the user to see which Processes will be deployed as well as the Swagger Specification. If a Published version is no longer valid, for example due to a used Process being deleted, then it can no longer be Deployed.
​

Frends supports editing imported Swagger Specifications. The Base path of an Swagger Spec can not be changed once it has been imported. 

Note that editing a Swagger Specification will override the current Swagger Specification, it will not create a rollback point by default. If you want a rollback point before editing, press Deployment and choose "Save and deploy". This will create a new version of the Specification and allow you to roll back at a later stage. It's not mandatory to go trough with the Deploy step.

Once a Swagger Specification has been imported, Frends can create Processes matching the API operations defined in the specification. 

A process generated from an API Specification will contain an API Trigger. The Trigger will give the Process access to all expected variables passed to the endpoint, and will even cast them to the correct type. 

A generated Process will also come with pre-generated responses. For example, if an endpoint is defined to return a Pet object on success and an Error object otherwise, then the Process will contain both of these responses upon creation, complete will expected parameters (as long as Swagger Specification contains all required information, of course). Whatever happens in between the trigger and the responses is up to the user.

Note that some settings that are defined in the Swagger specification are set on a process level. Supported schemas as well as Authentication will be set by the API Trigger, and might differ from what has been defined in the Specification. 

Once API is created the basepath cannot be edited, because all operation URIs are based on it. Version number can be added to basepath, if multiple versions are needed. The benefit of having e.g. different basepaths for v1 and v2 of the APIs is that then you can have both deployed in the same environment.

FRENDS will add "api" to the basepath upon save, e.g. example.com/api/foo/bar/v3, if it doesn't have it already. The /api prefix is because you can have simple HTTP triggers as well, the API triggers have their own reserved prefix, so there are no route conflicts, e.g. with HTTP trigger with route /foo/bar and API trigger /api/foo/bar

A process that has been created from an API Operation is linked to the API Specification that created it. That means the Process will be deployed when the API is deployed, and the API Deployment will make sure the right version of that process is deployed. 

If you wish to unlink a process from an API, to example create a new Process for that API Operation, simply click "Unlink Process". An unlinked Process can easily be re-linked to an API.
​

Frends detects when a Swagger Operation has changed for a Process with an API Trigger. This can happen when importing a new version of a Specification or when editing the Swagger Specification - for example an operation can gain an extra parameter, or there's a schema definition change.

Frends offer the functionality to update the Process' API trigger to match the new Swagger Specification. Note that this only updates the trigger- if the expected responses have changed, then it's up to the user to modify those. 
​

Responses are defined in a Swagger operation by HTTP status codes. For codes beginning with 2 or 3 (success / redirection), a Return element will be generated. For others, a Throw element will be generated. 

Note that the behaviour of these two elements are different.

A Throw element will end the Process in an error state, and if used in a Scope or a loop, it'll end the Process execution without continuing. Throw will also cause Error handlers to trigger. 

A Return will end the Process in a success state, and will continue executing if used in a Scope or loop.  

If you need to send out an error response but do not want the behaviour that comes with a Throw element just add a Return element with the same settings as the Throw. 

Deleting from a non-Development environment only removes the deployed processes and the deployed API Specification - they will still exist in the Development environment and can be re-deployed from there. Deleting from the Development environment removes the API as well as the linked Processes. It's only possible to delete the API from the Development environment if it's not deployed in other environments. 

Active processes part of an API Specification can be found, explored and tested from the Agent API Discovery page. By navigating to https://<agent url>:<port>/api/docs/, a list of active specifications will be shown. By navigating to a Specification, each active operation can be explored and tested.
​

           
​