From 296d74d9778e7a47b25b5d26bf131c2df5c3aa5e Mon Sep 17 00:00:00 2001 From: Martyn Davies Date: Thu, 30 Nov 2023 14:27:50 +0100 Subject: [PATCH] move comlinks overview to reference section --- docs/reference/what-are-comlinks.mdx | 55 ++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 docs/reference/what-are-comlinks.mdx diff --git a/docs/reference/what-are-comlinks.mdx b/docs/reference/what-are-comlinks.mdx new file mode 100644 index 00000000..2f767734 --- /dev/null +++ b/docs/reference/what-are-comlinks.mdx @@ -0,0 +1,55 @@ +# 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/.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](/docs/reference/glossary#provider) + +### Comlink Profile + +**File:** `superface/.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](/docs/reference/glossary#profile) + +### Comlink Map + +**File:** `superface/..map.js` + +**Created by:** `superface map` + +Describes implementation details for fulfilling a business capability from a Comlink Profile. + +[More details on Maps](/docs/reference/glossary#map) + +## 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: + +- [Node.js](/docs/examples/nodejs) +- [Python](/docs/examples/python) +- [Cloudflare Workers](/docs/examples/cloudflare-workers)