Skip to main content

Getting started

Superface is all about you, the consumer of API capabilities. To get started, first pick a capability and its provider, install it to your App and use Superface OneSDK to make the call.

info

This guide is more detailed version of the in-product Getting started available at superface.ai.

You don't need an account at superface.ai to follow this guide.

Superface in 3 minutes​

The following steps will guide you how to quickly get started with Superface and OneSDK.

Prerequisites

This guide assumes you have Node.js version 14 or newer installed.

Pick a capability​

Decide what capability you would like to use in your App. A capability is described by its profile with unique ID.

In this guide we will use the capability List user repositories of a VCS like GitHub or GitLab. Its ID is vcs/user-repos.

Capability details

To see a detailed description of the capability, check the vcs/user-repos profile page.

Pick a provider​

The next step is to pick a provider you would like to use. In this guide we will use the github.

Additional providers

Find the list of supported capability providers at vcs/user-repos profile page.

Install OneSDK​

In your App directory, install the OneSDK library:

npm install @superfaceai/one-sdk

Install the capability​

Next, add the vcs/user-repos capability to your App using the Superface CLI:

npx @superfaceai/cli install vcs/user-repos

Configure the provider​

The next step is to configure the provider. In our case we configure github for capability profile vcs/user-repos:

npx @superfaceai/cli configure github --profile vcs/user-repos
Provider authentication

In many cases you also need to set up provider credentials. Since we are using the unauthenticated GitHub API we can skip it for now.

To learn how to handle API credentials, see Setting provider API keys.

Code​

Finally, use OneSDK in your App. Create the index.js file with the following JavaScript code:

index.js
const { SuperfaceClient } = require('@superfaceai/one-sdk');
const sdk = new SuperfaceClient();

async function main() {
  // Load the capability profile
  const profile = await sdk.getProfile('vcs/user-repos');

  // Invoke the capability use case
  const result = await profile
    .getUseCase('UserRepos')
    .perform({
      user: 'superfaceai',
    });

  // Handle the result
  try {
    const data = result.unwrap();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

main();

Run​

With the capability installed, provider configured, and OneSDK, it is the time to execute your App:

node index.js
Example output
{
  repos: [
    { name: 'ast-js', description: undefined },
    {
      name: 'astexplorer',
      description: 'A web tool to explore the ASTs generated by various parsers.'
    },
    {
      name: 'cli',
      description: 'Superface CLI provides access to Superface tooling from the CLI.'
    },
    {
      name: 'demo-ballistic-sombrero',
      description: 'Demo of Koana Islands Weather Alerts provider'
    },
    {
      name: 'demo-koana-islands',
      description: 'Demo of Koana Islands Weather Alerts'
    },
    {
      name: 'demo-winter-beechnut',
      description: 'Demo of an alternative Koana Islands Weather Alerts provider'
    },
    { name: 'docs', description: 'Official Superface documentation' },
    { name: 'email-demo', description: undefined },
    {
      name: 'example-glitch-email',
      description: 'Glitch example showcasing email failover on SendEmail use case'
    },
    {
      name: 'example-glitch-geocode',
      description: 'Glitch example showcasing Geocode use case'
    },
    {
      name: 'example-glitch-reverse-geocode',
      description: 'Glitch example showcasing ReverseGeocode use case'
    },
    {
      name: 'language-client-vscode',
      description: 'VS Code extension that provides a client for the Superface Language server and syntax highlighting definitions.'
    },
    { name: 'language-server', description: undefined },
    {
      name: 'one-sdk-js',
      description: 'Superface core client library'
    },
    {
      name: 'parser',
      description: 'Superface profile and map format parser'
    },
    {
      name: 'profiles',
      description: 'Source repository of public profiles'
    },
    { name: 'release-changelog-action', description: undefined },
    { name: 'resilient-email-tutorial', description: undefined },
    {
      name: 'service-client',
      description: 'Library provides client for superface backend apis.'
    },
    {
      name: 'spec',
      description: 'Comlink Specification (Comlink, a new interface description and integration language) '
    },
    { name: 'station', description: 'Superface capabilities' },
    {
      name: 'superdriver',
      description: 'DEPRECATED: The original version of Superface SDK based on ALPS profile and OAS extensions. Do not use.'
    },
    { name: 'superface-cli', description: 'Superface CLI tool' },
    {
      name: 'testing-lib',
      description: 'Library to enable easier testing of capabilities.'
    }
  ]
}

Check the HTTP communication​

Set the environment variable DEBUG to superface:http* to see API calls from OneSDK to GitHub API:

DEBUG="superface:http*" node index.js
caution

This can print out potentially sensitive information.

Set the DEBUG environment variable to superface* to see everything what is going in under the hood.

Understand runtime integration​

During the App runtime OneSDK downloaded a Comlink map from Superface servers. The Comlink map instructs the OneSDK how to make the direct call to GitHub API to perform the capability.

You can always check the Comlink map at profile's detail page for the given provider by clicking the "raw" link. For example here's the latest map for vcs/user-repos and github.

Next step​

With your first capability set up, you can now start monitoring the integrations in Superface insights.