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.

1. Start with creating a new directory superface in the root of your project.
2. 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.
3. Add the provider. The provider name is the same as the filename. So the provider with name mailchimp have corresponding filename mailchimp.provider.json.
4. 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.