Skip to main content

Comlink

Overview​

Comlink is description language for autonomous APIs. It allows you to declaratively describe your API integrations in a way that separates the design-time semantics from the run-time implementation details. In other words, Comlink allows for defining the words we use to describe the capability of an API separate from the details for implementing that capability.

To learn how to use the Comlink language with Superface and our tools and services, check out our guides.

Comlink Profile

Describe business capabilities apart from the implementation details

Comlink Profile

Comlink Map

Describe implementation details for fulfilling a business capability from a Comlink Profile

Comlink Map

Comlink Provider

Define a provider's API services and security schemes to use in a Comlink Map

Comlink Provider

If you're a tooling author, please refer to our formal language specifications.

Motivation​

It creates challenges for developers when API description formats mix together design-time and run-time details.

  • Every API needs its own OpenAPI file to describe the implementation. This is one of the biggest struggles developers have when they're integrating with APIs. Since the semantics and implementation are mixed together, developers have to write separate integrations for each API they use even when those APIs provide the same capabilities. This takes time and money to build, maintain, and evolve these integrations—time and money that could be spent elsewhere.
  • Nothing can change at runtime. Since the semantics and implementation details are mixed together, we can't react to any changes while our software is running. Any implementation change requires redeployment.

Comlink addresses these problems by separating the design-time and run-time descriptions by providing Comlink Profile for describing business capabilities and Comlink Map for implementation details and how to map API providers and their services to business capabilities.

An example of this would be using Comlink Profile to describe how to send emails, using Comlink Map as describing implementation details for sending emails with Sendgrid, and Comlink Provider for describing Sendgrid's services and security schemes.

Quick Examples​

These are Comlink examples at a glance. They show how you can use Comlink to separate the capability from the implementation by using the Complink Profile to describe the capability and using the Comlink Map to describe the implementation.

Profile for sending emails​

Here is an example of a Comlink Profile for sending emails. The use-case, inputs, result, and error are defined apart from implementation details. This profile declaratively describes the use-case so it can be reused across different API providers.

Profile for sending email: send-email.supr
"""
Send Email
Send one transactional email
"""

name = "communication/send-email"
version = "1.1.1"

"""
Send transactional email to one recipient

Email can contain text and/or html representation
"""
usecase SendEmail unsafe {
  input {
    from!
    to!
    subject!
    text
    html
  }

  result {
    messageId
  }

  error {
    title
    detail
  }
}

Mapping an email provider to the send email profile​

This is a Comlink Map that maps the inputs, result, and error defined in a Comlink Profile to the actual implementation which would include HTTP requests and responses and their respective JSON bodies.

Map Postmark provider to Send Email profile: send-email.postmark.suma
// API Reference: https://postmarkapp.com/developer/api/overview

profile = "communication/send-email@1.1"
provider = "postmark"

map SendEmail {
  http POST "/email" {
    security "server_token"

    request "application/json" {
      body {
        From = input.from
        To = input.to
        Subject= input.subject
        TextBody = input.text
        HtmlBody = input.html
      }
    }

    response 200 "application/json" {
      map result {
        messageId = body.MessageID
      }
    }

    response 422 "application/json" {
      map error {
        title = "Invalid inputs"
        detail = body.Message
      }
    }

    response 401 "application/json" {
      map error {
        title = "Unauthorized"
        detail = body.Message
      }
    }

    response 403 "application/json" {
      map error {
        title = "Forbidden"
        detail = body.Message
      }
    }

    response 500 "application/json" {
      map error {
        title = "Internal server Error"
        detail = body.Message
      }
    }
  }
}

Provider definition for an email provider​

Comlink keeps the provider details separate as well so they can be reused in other Comlink Maps. This example shows the Provider Definition for Postmark which includes their services and security schemes.

Provider definition for Postmark: postmark.provider.json
{
  "name": "postmark",
  "services": [
    {
      "id": "default",
      "baseUrl": "https://api.postmarkapp.com"
    }
  ],
  "defaultService": "default",
  "securitySchemes": [
    {
      "id": "server_token",
      "type": "apiKey",
      "in": "header",
      "name": "x-postmark-server-token"
    }
  ]
}