Skip to main content

Comlinks overview

Comlink (short for Communication Link), is an open source DSL (Domain-Dpecific Language) for defining API connectors. It allows for declarative descriptions of API integrations in a way that separates the design-time semantics from the run-time implementation details.

A Comlink describes a use case, and how that use case should be executed using a specific API provider. They are at the heart of how the CLI and OneSDK work with the AI to turn your use case into the code that can be used to achieve it.

The Superface CLI is your starting point for creating Comlinks, it will output the files that are part of what we refer to as 'a Comlink' for each use case you want to create.

Comlinks are made up of three files, a Provider, a Profile, and a Map. All three are used with Superface's OneSDK to execute an API use case.

File: superface/<api-provider-name>.provider.json

Created by: superface prepare

Define an API provider's API services, base URL and security schemes to use in a Comlink Map. It tells Superface where to connect to, and how to authenticate any requests.

More details on Providers

File: superface/<use-case-name>.profile

Created by: superface new

Describes use case specific business capabilities separate from the implementation details, including what input and response objects are required, what error states are available and what example input and output objects should look like.

More details on Profiles

File: superface/<use-case-name>.<api-provider-name>.map.js

Created by: superface map

Describes implementation details for fulfilling a business capability from a Comlink Profile.

More details on Maps

Comlinks are API connectors used by Superface OneSDK to connect the application you are building to external APIs.

Once you have created a Comlink you have everything you need to start implementing that use case into your application.

Check out examples of implementations of OneSDK, with Comlinks: