NAV
cURL JavaScript

The Waylay Python SDK (beta)

IMPORTANT NOTICE

This software is currently in beta phase, which implies

Please contact your Waylay representative if you need additional support.

Basic concepts

Client

The WaylayClient is the main class of the Python SDK. It holds a configuration and one or more services. You can use the method list_root_urls to see a list of supported services and their configured endpoints.

from waylay import WaylayClient

client = WaylayClient.from_profile()
waylay_client.list_root_urls()
> {'analytics': 'https://ts-analytics.waylay.io',
 'byoml': 'https://byoml.waylay.io'}

Service, Resource, Action

The waylay client is hierarchically structured, mostly reflecting the structure of the underlying REST api exposed by the Waylay Platform.

the following example uses

  • the service analytics,
  • the resource query and
  • the action data

to retrieve timeseries data with a predefined query named 151CF-temperature.

waylay_client.analytics.query.data('151CF-temperature`)

See also this overview of currently supported services, resources and actions.

Configuration

The WaylayConfiguration class manages authentication and endpoint configuration for the waylay services.

When creating a client, you either provide all the needed information, or you load it from a local file named after the profile property of the configuration.

In interactive enviroments, loading a profile configuration that does not yet exist will prompt the user for information.

from waylay import WaylayClient

client = WaylayClient.from_profile('my_config')
Authenticating to the Waylay Platform
... (other prompts) ...
> apiKey : aaaa3a270351393485912a1d
> apiSecret : ········
> Do you want to store these credentials (profile=my_config)? [Y]: y
Credential configuration stored as 
   /Users/me/Library/Application Support/Waylay/python_sdk/.profile.my_config.json
Please make sure this file is treated securely.
If compromised, _Revoke_ the api-key on the Waylay Console!

Authentication

The following authentication information is supported in the Waylay Client

using apiKey and apiSecret (client credentials)

import os
api_key = os.getenv('WAYLAY_USER_ID')
api_secret = os.getenv('WAYLAY_USER_SECRET')
waylay_client_from_cc = WaylayClient.from_client_credentials(api_key, api_secret)

This is the normal authentication method, also used in the interactive authentication (from_profile).

Each (authorised) waylay user can generate one or more apiKey and apiSecret pairs by logging into the Waylay Console [>Settings>Authentication Keys].

A client configured this way will obtain a JWT Token form the waylay accounts service and use this to make REST api calls. When the token expires, it is renewed.

Hence the client will remain authenticated until the corresponding key is revoked AND the last JWT token has expired.

using apiKey and apiSecret (application credentials)

import os
api_key = os.getenv('WAYLAY_APPL_ID')
api_secret = os.getenv('WAYLAY_APPL_SECRET')
waylay_client_from_cc = WaylayClient.from_application_credentials(api_key, api_secret)

Application credentials can only be created by sufficiently authorised support staff. They otherwise function as client credentials.

using a waylay Token

jwt_token = get_token_from_somewhere_else()
waylay_client_from_token = WaylayClient.from_token(signed_jwt_token)

Your integration solution might already have received a token elsewhere, e.g. using an online identity provider.

Note that this client will no longer work when the token expires.

overriding endpoint configuration

this example hypothetically assumes that you have your own waylay deployment exposed through an internal https://api-gateway.my-network/waylay gateway

from waylay import WaylayConfig, WaylayCient, ClientCredentials 

# accounts_url points to your deployment of the `accounts` auth service
accounts_url = 'https://api-gateway.my-network/waylay/accounts'
waylay_config = WaylayConfig(
    credentials=ClientCredentials(api_key, api_secret, accounts_url),
    profile='via_my_gateway',
    settings_overrides= {
        'byoml': 'https://api-gateway.my-network/waylay/byoml'
    }
)
waylay_new_client = WaylayClient(waylay_config)

or using a stored profile

waylay_config.store()
waylay_new_client = WaylayClient.from_profile('via_my_gateway')

In most cases, a client will during authentication be self-configured with the service endpoints relevant for your tenant (as configured in the global settings by your adminstrator).

If this doesn’t work out for you (e.g. when testing deployments other that the Waylay Saas production cluster), you can provide overrides.

Coming up …

Please consult the python-sdk demo site for examples on the concrete usage of the current (beta!) API.

Once this API has gone through enough feedback and review cycles, general principles and generated API documentation will be made available.