Partner Integration

PolyScale’s partner integration make it simple to offer a fully autonomous database cache as part of your product offering. This can be utilizing PolyScale’s serverless edge network, or by deploying your own private PolyScale network, dedicated to your customers.

If you are interested in integrating with PolyScale, please contact us.

Overview

From an end user perspective, integrating PolyScale requires just a simple update to the database connection string; that is, rather than connect an application directly to a database, the traffic is routed via PolyScale as an intermediary.

The goal of the integration can be thought of as successfully providing the user with a valid PolyScale database connection string. This is achieved by making two changes to the origin connection string:

• Hostname - update the hostname to use PolyScale’s edge network psedge.global
• Cache ID - provide the PolyScale unique cache identifier to identify where PolyScale should route the traffic to. The cache id is generated upon cache creation. The syntax of how this is included within the connection string varies depending upon database type. You can read more about getting connected here.

With this connection string context, the integration workflow can be broken down into three sections:

1. OAuth Applications - using OAuth, validate a user is authorized to work with PolyScale
2. Cache Creation - using the PolyScale API, create a new cache or utilize an existing cache to return the cache id.
3. PolyScale Connection String - Using the unique cache identifier from step 2, generate and return a PolyScale connection string to the user

With a PolyScale connection string returned, you are then able to make the connection string available within the integrating application. For example, it may be saved as an environment variable.

The following sequence diagram provides an overview of the steps involved:

Integration sequence overview.

Cache Creation

In order to create a cache, the PolyScale API (api.polyscale.ai/v1/caches) requires the following inputs:

• Cache name - a name to identify the cache within PolyScale
• Database type - the type of origin database
• Database hostname - the hostname of the origin database
• Database port - the port of the origin database

Note that no database username or password is required. Once submitted via the API, PolyScale will return the unique cache id. It is then the requirement of your integrating application to generate a valid PolyScale connection string using the cache id to return to your user.

Input Verification

Depending upon whether your integrating application has access to the origin database connection string, will dictate if any of the required cache inputs will be manually input by the end user. For example, if the integrating application is a database provider, it is likely that the type, hostname and port are all available without the user's interaction. If however your integrating application does not have these credentials, a web form could be used to collect these from the end user. Care should be taken to validate the form inputs; for example, validate that the database hostname resolves.

PolyScale Connection String

With a cache id returned from the cache creation step, the final task is to construct a valid PolyScale connection string. This is simple string manipulation. The resulting connection string can then be saved for future use, making sure that it is treated in the same security context as the direct database connection string.

The format of the PolyScale connection string will take one of two forms depending upon the database type:

Postgres Connection String

To generate a valid PolyScale connection string for Postgres:

• set the hostname to use psedge.global
• pass the cache id using the application_name parameter key

Example: postgres://[USERNAME]:[PASSWORD]@psedge.global:5432/[DATABASE]?application_name=[CACHE_ID]

MySQL, MariaDB, MS SQL Connection Strings

To generate a valid connection string for all databases other than Postgres:

• set the hostname to use psedge.global
• prepend the database username with the cache id and a hyphen

Example: mysql://[CACHE_ID]-[USERNAME]:[PASSWORD]@psedge.global:3306/[DATABASE]

OAuth Applications

With OAuth applications you can grant third-party services access to your customer’s PolyScale resources via the PolyScale API.

Access Scopes

There are two kinds of access scopes:

• read access - allows applications to view resources
• write access - allows applications to modify resources

Supported scopes

The currently supported scopes are:

• caches:read - allows reading caches
• caches:write - allows creating, updating and deleting caches
• cacheRules:read - allows reading cache rules
• cacheRules:write - allows creating updating and deleting cache rules

Creating OAuth Applications

OAuth applications can be created at the PolyScale user level or the workspace level. Creating OAuth applications at a workspace level will enable all admin users of that workspace to manage the applications. User level applications can only be managed by that user.

To create an OAuth application at the user level go to Settings → Account → Integrations and press "Create" in the section titled "OAuth Apps". Set a name that helps your users identify your application. Make sure to also set the necessary scopes that your application needs and the redirect URIs you want to enable. Additionally you can add a URL to a logo and a homepage to help users identify your application.

After submitting the form, you'll be presented with the OAuth client id and client secret. Make sure to save the secret somewhere safe, as you'll not be able to see it again. You'll need to use the client id and client secret when interacting with the PolyScale OAuth server as required by the OAuth2.0 protocol.

tip

Make sure to save the OAuth client secret somewhere safe, as you'll not be able to see it again.

To create an OAuth application at the workspace level open the workspace and go to Settings → Workspace → Integrations.

OAuth Flow

PolyScale OAuth integrations currently only supports the OAuth2.0 Authorization Code Grant type.

The OAuth2.0 server automatically issues a refresh token alongside the access token, enabling integrations to automatically refresh expired access tokens.

The PolyScale authorisation server is available at https://oauth.polyscale.ai.

• Authorisation Path - /oauth2/auth

• Token Path - /oauth2/token

Authorizing OAuth Applications

When a third-party application requests consent for accessing your resources on your behalf you'll be prompted to select a workspace to authorize access on. The application will only be able to access resources associated with this workspace.

Make sure to also review the requested access scopes before authorizing the request.

Authorized OAuth applications will be listed under Settings → Account → Integrations. Here you can also revoke consent on a per-application basis or revoke consent for all applications. Revoking consent will invalidate any issued tokens to prevent the applications from accessing your resources.

Interacting with the PolyScale API

The PolyScale api uses bearer token authentication. Provide the OAuth2.0 access token in the Authorization header as Bearer [[ACCESS_TOKEN]].