@superfaceai/one-sdk

Website | Get Started | Documentation | Discord | Twitter | Support

Superface OneSDK

One SDK for all the APIs you want to integrate with.

OneSDK is a universal API client which provides an unparalleled developer experience for every HTTP API. It enhances resiliency to API changes and comes with built-in integration monitoring and fail-overs.

For more details about Superface visit how it works and get started.

Important Links

• Superface website
• Get Started
• Documentation
• Discord

Install

To install OneSDK into a Node.js project run:

npm install @superfaceai/one-sdk

or Yarn:

yarn add @superfaceai/one-sdk

Usage

💡 For quick usage example, check get started documentation.

With OneSDK everything revolves about your application's use cases for an API. To get started, first install a use case profile using the Superface CLI. In the project directory, run:

npx @superfaceai/cli install <profileName>

The CLI creates a configuration file in superface/super.json.

Next you configure a provider for the use-case:

npx @superfaceai/cli configure <providerName> -p <profileName>

CLI may instruct you about setting up API keys if the provider needs them.

In your code, you initialize the SDK instance, load the profile and perform the use-case:

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

const sdk = new SuperfaceClient();

async function run() {
  const profile = await sdk.getProfile('<profileName>');

  const result = await profile.getUseCase('<usecaseName>').perform({
    // Input parameters
  });

  console.log(result.unwrap());
}

run();

This code will use the first provider by priority as defined in super.json file. You can explicitly set the provider for perform:

 async function run() {
   const profile = await sdk.getProfile('<profileName>');

+  const provider = await sdk.getProvider('<providerName>');

   const result = await profile.getUseCase('<usecaseName>').perform(
     {
       // Input parameters
     },
+    { provider }
   );

   console.log(result.unwrap());
 }

To find available use-cases, sign up for Superface and visit Use-cases Catalog. If you are missing a use case, let us know. You can always add your own use-case or API provider.

Support

If you have any questions, want to report a bug, request a feature or you just want to talk, feel free to open an issue or hop on our Discord server.

You can find more options for reaching us on the Support page.

Security

Superface is not a proxy. The calls are always going directly from your application to API providers. The API secrets are never sent anywhere else but to the used provider's API.

OneSDK accesses superface/super.json file and accesses cache in superface/.cache directory. It also accesses local maps, profiles, and provider configuration if specified in the super.json file. Non-local maps, profiles and provider configuration are loaded from the Superface network registry in the runtime and cached locally. OneSDK sends diagnostic usage report to Superface as described below.

More about the journey of the secrets within OneSDK can be found in Security.

Metrics Reporting

OneSDK sends anonymized information about use-cases usage to Superface services. This info is anonymized, rate limited and allows you to monitor your integrations on the dashboard.

There are three kinds of metrics reported one is sent when the client instance is created, one after each perform (reporting success or failure), and one when a provider failover happens.

The reports can be disabled with environment variable:

SUPERFACE_DISABLE_METRIC_REPORTING=true

For metrics to be successfuly sent, the application needs to be properly exited, i.e. there should be no unhandled Promise rejections or exceptions.

Contributing

We welcome all kinds of contributions! Please see the Contribution Guide to learn how to participate.

License

OneSDK is licensed under the MIT License.

© 2021 Superface s.r.o.

Changelog

[1.1.0] - 2021-12-22

Added

• Pass integration parameters in perform

Fixed

• Display query parameters in URL with DEBUG=superface:http:sensitive