one-sdk

Website | Get Started | Documentation | GitHub Discussions | Twitter | Support

Superface OneSDK

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

OneClient 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.

Important Links

• Superface website
• Get Started
• Documentation
• Support

Install

To install OneSDK into the project, run:

python3 -m pip install one-sdk

Setup

OneClient uses three files (also called Comlink) which together make the integration:

• Profile - describe business capabilities apart from the implementation details, what is expected as input and what will be the result. Profile name have optional scope before / and required name [scope/]<name>
• Provider - Define a provider's API services and security schemes to use in a Comlink Map
• Map - describe implementation details for fulfilling a business capability from a Comlink Profile

To glue all the parts together, OneClient uses name and file structure convention.

.
└── superface/ - directory with all the Comlinks in project root
    ├── <profileScope>.<profileName>.profile - profile file
    ├── <providerName>.provider.json - provider file
    ├── <profileScope>.<profileName>.<providerName>.map.js - map file
    └── ... - repeat for all the Comlinks

Send email example

As an example, lets send an email with Mailchimp. The use-case is described in the profile communication/send-email and the map with implementation.

• Start with creating a new directory superface in the root of your project.
• Add the profile. Because profile name contains have scope we need to replace / with .. So, the profile with name communication/send-email have corresponding filename communication.send-email.profile.
• Add the provider. The provider name is the same as the filename. So the provider with name mailchimp have corresponding filename mailchimp.provider.json.
• Add the map. Map connects profile and provider, so the filename is consists of both as well communication.send-email.mailchimp.map.js.

The final structure should look like this:

.
└── superface/
    ├── communication.send-email.mailchimp.map.js
    ├── communication.send-email.profile
    └── mailchimp.provider.json

Use

Create __main__.py file with following content and update:

import sys
from one_sdk import OneClient, PerformError, UnexpectedError

client = OneClient()
profile = client.get_profile("<profileName>")
use_case = profile.get_usecase("<usecaseName>")
try:
    r = use_case.perform(
        {
            # Input parameters as defined in profile:
            '<key>': '<value>'
        },
        provider = "<providerName>",
        # Provider specific integration parameters:
        parameters = {
            '<integrationParameterName>': '<integrationParameterValue>'
        },
        security = {
            # Provider specific security values:
            '<securityValueId>': {
                # Security values as described in provider or on profile page
            }
        }
    )
    print(f"RESULT: {r}")
except PerformError as e:
    print(f"ERROR RESULT: {e.error_result}")
except ValidationError as e:
    print(f"INVALID INPUT: {e.message}", file = sys.stderr)
except UnexpectedError as e:
    print(f"ERROR:", e, file = sys.stderr)
finally:
    client.send_metrics_to_superface()

Then run the script with:

python __main__.py

License

OneSDK is licensed under the MIT License.

© 2023 Superface s.r.o.