Website | Get Started | Documentation | GitHub Discussions | Twitter | Support
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 provider failover.
For more details about Superface, visit How it Works and Get Started.
To install OneSDK into a Node.js project, run:
npm install @superfaceai/one-sdk
or Yarn:
yarn add @superfaceai/one-sdk
💡 For a quick usage example, check out Get Started.
Superface is all about use cases. You can start with one of the publically available use cases from the Superface Catalog.
Once you've got your use case, you need to provide OneSDK with:
These can be found on the profile page (e.g. vcs/user-repos). Security values need to be obtained through the relevant provider (e.g. on their website, in your account settings, by contacting them, etc.).
const { SuperfaceClient } = require('@superfaceai/one-sdk');
const sdk = new SuperfaceClient();
async function run() {
const profile = await sdk.getProfile({
id: '<profileName>',
version: '<profileVersion>',
});
const result = await profile.getUseCase('<usecaseName>').perform(
{
// Input parameters in format:
'<key>': '<value>',
},
{
provider: '<providerName>',
parameters: {
// Provider specific integration parameters in format:
'<integrationParameterName>': '<integrationParameterValue>',
},
security: {
// Provider specific security values in format:
'<securityValueId>': {
// Security values as described on profile page
},
},
}
);
console.log(result.unwrap());
}
run();
If you are missing a use case, let us know! You can also always add your own use-case or API provider.
As your project grows in size and complexity, you may find it useful to have a central location for configuring details concerning your API integrations. There are also some features that cannot be used with the simple approach described above, namely:
For these cases, there's Superface configuration. To find out more, visit Advanced Usage.
Superface is not a proxy. The calls are always going directly from your application to API providers. Their contents are never sent anywhere else but to the selected provider's API.
OneSDK accesses superface/super.json
file if instructed to, and accesses cache in node_modules/superface/.cache
directory. It also accesses local maps, profiles, and provider configuration as per configuration. Non-local maps, profiles and providers are loaded from the Superface remote registry at runtime, and cached locally. OneSDK also sends diagnostic usage report to Superface as described below.
More about how OneSDK handles secrets can be found in SECURITY.
Superface allows you to monitor your integrations and display the metrics on a dashboard. There are three kinds of metrics reported:
These metrics contain no personal information nor the contents of the API calls and are rate limited as to not impact performance.
Utilizing this functionality requires you to obtain and set a SUPERFACE_SDK_TOKEN
. For more information, see Integrations Monitoring.
However, even without an SUPERFACE_SDK_TOKEN
set, this data is sent anonymized to Superface services for diagnostic purposes. All metrics reporting can be disabled by setting an environment variable:
SUPERFACE_DISABLE_METRIC_REPORTING=true
For metrics to be successfuly sent, the application needs to exit properly, i.e. there should be no unhandled Promise
rejections or exceptions.
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 reach us in other ways through the Support page.
Only functions and APIs of entities below are a part of the public API, and can be safely relied upon not to break between semver-compatible releases.
Using other parts of this package is at your own risk.
Use of public APIs is described in the reference.
We welcome all kinds of contributions! Please see the Contribution Guide to learn how to participate.
OneSDK is licensed under the MIT License.
© 2023 Superface s.r.o.