Skip to main content

Run use case

This guide describes how to start using a locally developed use case in a 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.

Comlink profile and map files (.supr and .suma) needs to be compiled to their AST form (with .ast.json extension).

Run the following command to perform a one-off compilation:

npx @superfaceai/cli@latest compile

This will generate .ast.json files next to the existing source files linked from super.json file.

caution

The compilation is necessary after every change to local .suma and .supr files.

caution

The .ast.json files must be available in the runtime for OneSDK. We recommend to commit the .ast.json files to version control.

Run the app​

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

node app.js

Observe and debug API calls​

OneSDK uses debug, which is useful for observing the behavior of the SDK and troubleshooting. 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.