Getting started

Superface is all about providing you the best way to consume digital capabilities provided by APIs. This guide shows you how to pick a use case and its provider from our Catalog, and use Superface OneSDK to make the API call.

Superface in 3 minutes

The following steps will help you get started with Superface and OneSDK.

Prerequisites

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

Pick a use case

Pick a use case you would like to use in your app from the Superface catalog. Each use case is identified by a name, and an ID of its profile. Profiles are collections of related use cases.

If your use case or provider is missing, you can create the integration yourself by following How to Create a Capability guide or let us know and we'll add it to the catalog.

In this guide, we will work with the use case Get User Repositories which retrieves GitHub, GitLab or Bitbucket repositories of a specified user. Its profile ID is vcs/user-repos and the use case name is UserRepos.

To see a detailed description of the use case, 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. You can find the list of supported use case providers at vcs/user-repos profile page.

Provider authentication

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

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

Install OneSDK

In your app directory, install the OneSDK library:

npm install @superfaceai/one-sdk@2

Code

Now you can 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 profile identified by profile ID and version
  const profile = await sdk.getProfile('vcs/user-repos@2.0.1');

  // Load use case, pass use case name as argument
  const useCase = profile.getUseCase('UserRepos');

  // Invoke the use case, pass user in perform input parameter and provider name in perform options
  const result = await useCase.perform(
    {
      user: 'superfaceai', // use case input, in our case the username of a GitHub user or organization
    },
    {
      provider: 'github', // provider name
    }
  );

  // Print the result
  console.log(result.unwrap());
}

main();

Profile ID, use case name and provider name parameters

Note that we passed the previously picked profile ID vcs/user-repos as a parameter to the getProfile() function, use case name as a parameter to the getUseCase() function of the profile object, and provider name as parameter to the perform() function.

Run

It's time to run your app!

node index.js

Example output

{
  repos: [
    {
      name: 'astexplorer',
      description:
        'A web tool to explore the ASTs generated by various parsers.',
    },
    {
      name: 'banking-demo',
      description: 'Demo of Superface banking use-cases',
    },
    {
      name: 'chat-demo',
      description:
        'Express server for OAuth flow and examples of messaging use-cases for Discord and Slack',
    },
    {
      name: 'cli',
      description: 'Do not program API integrations! Install them.',
    },
    {
      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: 'Superface.ai & Comlink documentation. ',
    },
    { name: 'email-demo', description: undefined },
    // ... more repositories
  ];
}

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, like API keys and access tokens.

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

DEBUG="superface*" node index.js

Understanding runtime integration

During the runtime of the application, OneSDK downloads a Comlink map from Superface servers. The Comlink map instructs the OneSDK how to make the call to GitHub API in order to perform the use case.

OneSDK also downloads the Comlink profile, which contains the definition of the use case for runtime. You can also provide local maps and profiles stored alongside your source code.

You can always check the Comlink map at the profile's detail page for a 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 use case set up, you can now start monitoring the integrations in Superface insights.