Glossary
This glossary of terms refers to the latest versions of the Superface CLI and OneSDK. If you are looking for information on Superface CLI v3 or lower, or OneSDK version 2, you can find it in the Classic Glossary.
Use case
Use case (or integration use case) describes what the business needs from a specific integration. Technically, the use case defines an interface between the application and the integration provider, the schema of input and output (result) data, possible error conditions, and relevant documentation. It is a part of the profile.
For example, a SendEmail use case expects a to, from, subject, and text inputs. It will return a message ID as the result.
Use cases are written using the Comlink Profile language, and automatically generated by the Superface CLI:
"""
Send SMS Message
Send single text message
"""
usecase SendEmail unsafe {
input {
"Recipient email address. Multiple addresses are comma separated. Max 50."
to! string!
"Sender email address. To include a friendly name, use the format 'Your Name <sender@domain.com>'."
from! string!
"Email subject."
subject! string!
"Bcc recipient email address. Multiple addresses are comma separated. Max 50."
bcc string!
"Cc recipient email address. Multiple addresses are comma separated. Max 50."
cc string!
"Reply-to email address."
reply_to string!
"The HTML version of the message."
html string!
"The plain text version of the message."
text string!
}
result {
id! string!
}!
Profile
A profile contains one or more use cases, along with the version and general documentation for that group of use cases. It is identified by a name, with an optional scope separated by a slash, for example: communication/send-sms.
Profile's file has an extension .profile and it is created by the Superface CLI. It should be committed to a version control system and kept with the application's code.
Profiles are written using the Comlink Profile language, for example:
"""
Send Email
Send a single email
"""
name = "email-communication/email-sending"
version = "0.0.0"
"Sends an email to specified recipients with optional Bcc, Cc, reply-to, HTML and plain text versions."
usecase SendEmail unsafe {
input {
"Recipient email address. Multiple addresses are comma separated. Max 50."
to! string!
"Sender email address. To include a friendly name, use the format 'Your Name <sender@domain.com>'."
from! string!
"Email subject."
subject! string!
"Bcc recipient email address. Multiple addresses are comma separated. Max 50."
bcc string!
"Cc recipient email address. Multiple addresses are comma separated. Max 50."
cc string!
"Reply-to email address."
reply_to string!
"The HTML version of the message."
html string!
"The plain text version of the message."
text string!
}
result {
id! string!
from! string!
to! string!
created_at! string!
}!
error {
"Error message describing the reason for the failure."
error! string!
"HTTP status code associated with the error."
status! number!
"Information about the rate limit, if applicable."
rate_limit {
"The maximum number of requests allowed within the specified time window."
limit! number!
"The number of remaining requests within the current time window."
remaining! number!
"The time at which the rate limit will reset, in Unix timestamp format."
reset! number!
}!
}!
example InputExample {
input {
to = 'recipient@example.com',
from = 'Your Name <sender@example.com>',
subject = 'Hello, World!',
bcc = 'bcc@example.com',
cc = 'cc@example.com',
reply_to = 'reply@example.com',
html = '<p>Hello, World!</p>',
text = 'Hello, World!',
}
result {
id = 'placeholder',
from = 'placeholder',
to = 'placeholder',
created_at = 'placeholder',
}
}
}
Map
Map defines a provider-specific logic to fulfill the use case, i.e. what API endpoints need to be called, how to format requests and responses, and how authentication is performed.
Maps are fetched by OneSDK at runtime (i.e., when the particular profile is used with the particular provider for the first time) and can be also updated at runtime (e.g., to fix/handle breaking changes in the provider's API).
Map files have an extension .map.js. They specify the name of the provider and the profile, along with its major and minor version. For each use case defined in the respective profile, there is a corresponding function inside the map file.
Example of the map for email-communication/email-sending profile and the provider resend:
function SendEmail({ input, parameters, services }) {
const url = `${services.default}/email`;
const options = {
method: 'POST',
body: input,
headers: {
'Content-Type': 'application/json',
},
security: 'bearer_token',
};
const response = std.unstable.fetch(url, options).response();
const body = response.bodyAuto() ?? {};
if (response.status !== 200) {
const error = {
error: body.error || 'Error sending email',
status: response.status,
rate_limit: {
limit: parseInt(response.headers['x-ratelimit-limit'][0], 10),
remaining: parseInt(response.headers['x-ratelimit-remaining'][0], 10),
reset: parseInt(response.headers['x-ratelimit-reset'][0], 10),
},
};
throw new std.unstable.MapError(error);
}
const result = {
id: body.id,
from: body.from,
to: body.to,
created_at: body.created_at,
};
return result;
}
Provider
Provider (or integration provider) defines a set of base URLs (services), security schemes, and integration parameters. This information is used for reusability between maps, and as a security measure. Maps cannot send requests outside of defined services, and cannot read values passed to the authentication scheme.
From the perspective of Superface, a single provider does not have to correspond to a single company. Large companies, like Google, often have multiple unrelated APIs, each with its own provider (e.g. google-apis-maps or google-apis-computer-vision). Conversely, your provider can specify services from unrelated companies, if you need to use these services in a single map.
Provider definition is a JSON file adhering to the Comlink Provider schema. The provider is configured by the Superface CLI for particular profiles, which enables the respective maps to be used by OneSDK in the runtime. A provider is identified by its name, for example: resend.
Example of the resend provider:
{
"name": "resend",
"defaultService": "default",
"services": [
{
"id": "default",
"baseUrl": "https://api.resend.com"
}
],
"securitySchemes": [
{
"id": "bearer_token",
"type": "http",
"scheme": "bearer"
}
],
"parameters": []
}
Integration parameter
Integration parameters are provider-specific values which can be used in maps and provider definitions. A parameter's value can be specified either via an environment variable, or at runtime as an argument of the perform() method.
Common uses for integration parameters include:
- specifying alternate URL or regional domain for the provider's service (e.g. IBM Cloud Speech to Text provider)
- passing additional values required by the provider which cannot be covered by profile's input values (e.g. Mailgun DOMAIN parameter)
- passing user's OAuth2 Access Tokens at runtime (e.g. Twitter accessToken parameter)
OneSDK
OneSDK is a universal API client for Node.js. It is the primary way of using Superface integrations.
For more details, see OneSDK quick start and its GitHub repostiory.
Comlink
Comlink is a domain-specific language for declarative description of API integrations. It consists of three parts: Profile, Map, and Provider definition. Integrations written with Comlink are consumed by OneSDK.
For more details see Comlink reference.