Skip to main content

Run Capability

This guide describes how a capability can be used in any production Node.js application.

Prerequisites​

Configure provider authentication​

Optional

If the Provider JSON doesn't define any security schemes, or the map doesn't use security, you can skip this step.

If you've created a completely new Provider JSON definition in your project, it will not have its security schemes configured in the local superface/super.json configuration file.

Provider's security schemes must be configured in super.json since OneSDK will search for it when authenticating the requests during use case perform.

The specific provider section will look like the following example:

superface/super.json
{
  "profiles": {
    // ...
  },
  "providers": {
    "<provider-name>": {
      "security": []
    }
  }
}

Search in top-level providers object for the actual provider you want to configure.

Configure using CLI​

The easiest way to bootstrap the provider's security configuration is using Superface CLI.

superface configure <provider-name> -p <profile-name> --localProvider <path-to.provider.json> --localMap <path-to-provider-map.suma> -f

Replace the <profile-name>, <path-to.provider.json>, <provider-name->, and <path-to-provider-map.suma> in the command with the actual values.

Running the above command automatically creates security schemes configuration in super.json based on Provider definition. It also prepares expected environment variables (if any are required) inside a .env file.

Advanced users can configure the security manually instead.

Configure security in super.json manually​

If you configured security using CLI, you can skip this.

Configuring security manually

You'll need to provide a configuration based on the security scheme type. Currently the following schemes can be used:

Reading environment variables in super.json​

You can be prepend any value assigned in super.json with a dollar sign ($) to reference an environment variable.

{
  // ...
  "token": "$PROVIDER_API_TOKEN"
  // ...
}

When evaluating the above configuration, OneSDK will look for PROVIDER_API_TOKEN value in environment variables.

Configure Basic Auth scheme​

Use the following config and reference an existing security scheme from the Provider's JSON definition by an identifier.

superface/super.json
{
  "profiles": {
    // ...
  },
  "providers": {
    "<provider-name>": {
      "security": [
        {
          "id": "<scheme-id>",
          "username": "$PROVIDER_USERNAME", // will read `PROVIDER_USERNAME` from environment
          "password": "$PROVIDER_PASSWORD" // will read `PROVIDER_PASSWORD` from environment
        }
      ]
    }
  }
}

Replace <scheme-id> with the actual security scheme ID defined in the Provider JSON document. You can use your own values for username & password. However it's a common practice to supply these values via environment variables.

Configure Bearer Token scheme​

Use the following config and reference an existing security scheme from the Provider's JSON definition by an identifier.

superface/super.json
{
  "profiles": {
    // ...
  },
  "providers": {
    "<provider-name>": {
      "security": [
        {
          "id": "<scheme-id>",
          "token": "$PROVIDER_API_TOKEN" // will read `PROVIDER_API_TOKEN` from environment
        }
      ]
    }
  }
}

Replace <scheme-id> with the actual security scheme ID defined in the provider JSON document. You can use your own value for token. However it's a common practice to supply these via environment variables.

Configure API key in headers or query​

Use the following config and reference an existing security scheme from the Provider's JSON definition by an identifier.

superface/super.json
{
  "profiles": {
    // ...
  },
  "providers": {
    "<provider-name>": {
      "security": [
        {
          "id": "<scheme-id>",
          "apikey": "$PROVIDER_API_KEY" // will read `PROVIDER_API_KEY` from environment
        }
      ]
    }
  }
}

Replace <scheme-id> with the actual security scheme ID defined in the provider JSON document. You can use your own value for apikey. However it's a common practice to supply these via environment variables.

Set environment variables​

For apps running the capabilities that require authentication, you'll typically want to supply the providers' API keys via environment variables (see configuration above).

If .env file exists and you used the CLI, the required environment variables will be present in the file. Fill in the providers' API keys. Then install the dotenv package to load the .env file.

If .env file doesn't exist, you can find the expected environment variables in /superface/super.json. Any value that starts with a dollar sign ($) is a reference to an environment variable.

Write Node.js app​

Use the OneSDK to load and perform the use case:

app.js
// If you're using .env file, you should also install and init `dotenv` package
require('dotenv').config();
const { SuperfaceClient } = require('@superfaceai/one-sdk');

const sdk = new SuperfaceClient();

async function main() {
  const profile = await sdk.getProfile('scope/profile-name');

  const result = await profile
    .getUseCase('UseCaseName')
    .perform(/* Input object as defined in the profile */);

  console.info('Hooray!', result.unwrap());
}

main();

Replace scope/profile-name, UseCaseName and inputs for .perform method with the use case details you actually want to use.

info

For details on SuperfaceClient API, please consult OneSDK reference.

Run the app​

Now run the application to perform the use case and check the results:

node app.js
Offline Use

To use capability without the use of Superface remote registry. You have to import capabilities into project and ensure super.json has valid paths to your capabilities.

Observe and debug API calls​

OneSDK uses the debug package which is useful for observing the behavior of the SDK and debugging. To use it, set environment variable to DEBUG="superface*" before running the application:

DEBUG="superface*" node app.js

To observe just the API calls, you can use superface:http debug context:

DEBUG="superface:http*" node app.js
Sensitive Output

Using the superface:http* context will output full HTTP requests and responses including API keys and other sensitive data.