What’s new at Superface: November 2021

November has been a busy month at Superface. We've opened up registration and released lots of great new features. Cozy up and grab an eggnog as we share what we've been up to.

Registration is now open for all

Register for a Superface account and get access to the use-cases catalog and integrations monitoring dashboard. We have also prepared a sweet promo video for the occasion.

OneSDK and CLI hit version 1.0

With the public launch, we have also released 1.0 versions of OneSDK, Superface CLI, and supporting libraries. We're committed to backwards compatibility, so you can expect our APIs to remain stable.

We will publish release candidates for general testing under the next dist-tag.

New in catalog: Computer Vision, Natural Language Processing and others

You can find new use-cases and providers in our ever-growing catalog:

• communication/send-message for sending text messages over Slack
• computer-vision/face-detection detects faces and emotions in images using Google Cloud Vision API
• crm/contacts for managing customers and users in various systems; Crisp, Hubspot, Mixpanel, and Sendgrid are available
• crypto/exchange-rate fetches exchange rate of cryptocurrencies using Binance
• language/analyze-plain-text-sentiment analyzes emotions and prevailing sentiment in text with IBM Watson Natural Language Understanding and Google Cloud Natural Language APIs
• language/translate translates text using DeepL Translator
• speech/synthesis turns text into natural-sounding speech with Google Cloud Text-to-Speech and IBM Watson Text to Speech
• speech/recognize turns speech into text with AssemblyAI, and Speech to Text services by Google Cloud, IBM Watson, and Microsoft Azure

All use-cases from the catalog are maintained in the Station repository. If you are curious what we are working on, check out our open pull requests. And of course, you are more than welcome to contribute new providers and use-cases.

Integration parameters and examples in Comlink

Comlink is a domain-specific language (DSL) which powers Superface integrations. Recently, we have improved support for integration parameters and introduced examples into profiles.

Provider integration parameters

Some providers require additional information for working with their APIs. For example, calls to Twilio include “Account String Identifier” (SID) and IBM Cloud lets you pick a preferred region for their services. Unlike security values (API keys and access tokens) these information usually aren’t sensitive and in some cases can have a default value.

We call these values “integration parameters”. They are specified inside the provider definition file:

{
  "name": "ibm-cloud-natural-language-understanding",
  // ...
  "parameters": [
    {
      "name": "REGION",
      "description": "Your natural language understanding instance region (eu-de, us-east, ...)"
    },
    {
      "name": "INSTANCE_ID",
      "description": "Your natural language understanding instance id"
    }
  ]
}

With these parameters defined, maps can access them through parameters object:

map AnalyzePlainTextSentiment {
  http POST "/instances/{parameters.INSTANCE_ID}/v1/analyze?version=2021-08-01" {
    // ...
  }
}

We have improved the discovery of these parameters in our catalog and CLI. Now you can preview all the required parameters in the provider details.

See it in action on Analyze plain text sentiment IBM provider detail.

And the Superface CLI will inform you when configuring the provider:

$ npx @superfaceai/cli  configure ibm-cloud-natural-language-understanding -p language/analyze-plain-text-sentiment
Installing provider to 'super.json' on path 'superface/super.json'
Installing provider: "ibm-cloud-natural-language-understanding"
🆗 All security schemes have been configured successfully.
Provider ibm-cloud-natural-language-understanding has integration parameters that must be configured. You can configure them in super.json on path: superface/super.json or set the environment variables as defined below.
🆗 Parameter REGION with description "Your natural language understanding instance region (eu-de, us-east, ...)" has been configured to use value of environment value "$IBM_CLOUD_NATURAL_LANGUAGE_UNDERSTANDING_REGION".
Please, configure this environment value.
🆗 Parameter INSTANCE_ID with description "Your natural language understanding instance id" has been configured to use value of environment value "$IBM_CLOUD_NATURAL_LANGUAGE_UNDERSTANDING_INSTANCE_ID".
Please, configure this environment value.

By default OneSDK will look for the parameters in environment variables, but you can also define them directly in the super.json configuration file.

Profile examples

Comlink profile defines an interface, or “contract”, between your application and the provider-specific API. Profile specifies inputs, outputs, and error models. It is now possible to document example inputs with expected outputs or errors:

usecase ReverseGeocode {
  // ...
  example Successful {
    input {
      latitude = 37.423199,
      longitude = -122.084068
    }

    result [{
      addressCountry = 'us',
      addressLocality = 'Mountain View',
      addressRegion = 'CA',
      formattedAddress = 'Amphitheatre Parkway, Mountain View, CA 94043, United States of America',
      postalCode = '94043',
      streetAddress = 'Amphitheatre Parkway',
    }]
  }

  example Failed {
    input {
      latitude = 720,
      longitude = 540
    }

    error {
      title = 'Bad request',
      detail = 'The provided coordinates in query are invalid, out of range, or not in the expected format'
    }
  }
}

Examples are also rendered in the use-case’s detail, you can see it in action on Geocoding use-cases.

First Superface webinar

We have organized the first Superface webinar to show how easy it is to integrate multiple APIs and take advantage of provider fail-overs and other features. You can watch the recording on YouTube.

More to come

November was an important milestone for us, but we are just getting started. Expect more exciting news in 2022. Don’t forget to join our Discord and follow us on Twitter and LinkedIn.

From Superface, we wish you happy Holidays and a wonderful 2022!