Superface Blog
Published on

What’s new at Superface: November 2021

Authors
  • Name
    Jan Vlnas
    Title
    Developer Advocate
    Social media profiles

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.

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!

Single SDK for ATS, CRM, SMS and e‑mail APIs

Superface is a single API client for hundreds of APIs. Providing fast, stable, direct API integrations that do not compromise on speed or privacy.

Learn more

API Change Newsletter

Unlike many other APIs, we only publish changes that won’t break your app. However, they might break your world view of APIs!

Superface s.r.o. needs the contact information you provide to us to send you a monthly newsletter. You may unsubscribe from these communications at any time. For information on how to unsubscribe, as well as our privacy practices and commitment to protecting your privacy, please review our Privacy Policy.