DEV Community

Jan Vlnas for Superface

Posted on • Updated on • Originally published at superface.ai

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:

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"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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" {
    // ...
  }
}
Enter fullscreen mode Exit fullscreen mode

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.

Preview of integration parameters on IBM Cloud provider

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.
Enter fullscreen mode Exit fullscreen mode

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'
    }
  }
}
Enter fullscreen mode Exit fullscreen mode
Examples are also rendered in the use-case’s detail, you can see it in action on Geocoding use-cases.

Preview of input examples for ReverseGeocode use-case

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!

Top comments (0)