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.
What are Comlinks?
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.
Comlink elements
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.
Comlink Provider
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.
Comlink Profile
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.
Comlink Map
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.
What are Comlinks used for?
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: