aws-data-api-python-sdk 0.9.0b1

Python module to access AWS Data API's.

AWS Data API - Python SDK

This project contains a python SDK for AWS Data API's. Data API's give you the ability to create a new back end web service to handle core business data, without any coding or servers to manage. The Python SDK gives you a client that can create and interact with Data API's using a model similar to the AWS boto3 Python SDK.

AWS Data API's use URL Paths and HTTP Verbs to implement underlying actions against your data - for example HTTP GET for reads, or HTTP PUT for writes. However, the Python SDK provides more user friendly methods - such as get_item() or put_metadata().

Installation

The AWS Data API Python client is distributed through Pypi. To install:

pip3 install aws-data-api-python-sdk

this will install:

• boto3: The AWS Python SDK which is used for automating credential management.
• requests-aws4auth: Helper module that performs sigv4 signing of the requests you make to AWS Data API's
• shortuuid: Helper module to generate short, unique addresses

to check that it's installed correctly:

aws-data-api-python-sdk meyersi$ python3
Python 3.7.4 (default, Sep  7 2019, 18:27:02)
[Clang 10.0.1 (clang-1001.0.46.4)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import data_api_client as d
>>> print(d.__version__)
0.9.0b1

Setting Up Credentials

Data API Clients use the same process for setting up credentials as the AWS Python SDK, and the simplest way of setting up credentials can often be to either install the AWS command line client, or to setup and configure boto3. You can use a correctly configured boto3 environment to provide credentials to Data API, or you can explicitly set the access key, secret key, and session token using the control plane and client constructors.

Linking to Data API Endpoints

API endpoints for your client are cached in a local file, and can be refreshed at any time. Initially the endpoint addresses are not installed, and so you need to load them. To do this, we will create a Data API 'Control Plane' helper, and use it to build our connection set:

from lib.data_api_control_plane import DataApiControlPlane
region = os.getenv("AWS_REGION")
control_plane = DataApiControlPlane(tls=True, region_name=region)

Then we need to call the connect method:

def connect(from_url: str, 
			access_key: str, 
			secret_key: str, 
			session_token: str,
			force_refresh: bool = False
)

Arg	Purpose	Required
from_url	URL used to link your client environment to all Stages in an Account. This URL can be any valid Data API endpoint in your Account - any any Stage	Yes
access_key	The AWS Access Key to be used to call the API Endpoint	No
secret_key	The AWS Secret Access Key to be used to call the API Endpoint	No
session_token	The Session Token associated with a temporary STS Token	No
force_refresh	Boolean value - when True, will force the endpoints.json file to be reloaded from the endpoint. When False, the method will return immediately	No

For example:

access_key = 'MY ACCESS KEY'
secret_key = 'MY SECRET KEY'
session_token = 'SESSION TOKEN'

control_plane.connect(from_url="https://XXXXX.execute-api.eu-west-1.amazonaws.com/dev",
                      access_key=access_key,
                      secret_key=secret_key, 
                      session_token=session_token,
                      force_refresh=True)

If you want to see the endpoints for your Client, you can open the lib/endpoints.json, which will look something like this:

{
    "RefreshDate": "2020-09-02 12:32:13",
    "dev": {
        "DistributionDomainName": "dbfje2qy9pn4z.cloudfront.net",
        "Endpoint": "https://sdma0i6rek.execute-api.eu-west-1.amazonaws.com",
        "Stage": "dev",
        "URL": "https://my-custom-url"
    },
    "test": {
        "Endpoint": "https://txcoxv32dh.execute-api.eu-west-1.amazonaws.com",
        "Stage": "test"
    }
}

These are the internal GUID addresses per-stage that your client will connect to. If you prefer, you can also create this file manually or download it from a separate storage medium.

Creating a Client

Once the client environment is linked to your Endpoints, you can create a Client for the required Region and Stage:

my_client = DataAPIClient(
	stage: str, 
	region_name: str = None, 
	access_key: str = None, 
	secret_key: str = None,
	session_token: str = None
	service_endpoint: str = None, 
	tls: bool = True
)

Arg	Purpose	Required
stage	Links the Client to the specified Stage of the API, such as 'dev', or 'test', thus setting the endpoint that is called.	Yes
region_name	The AWS Short Region in which you are connecting. Used for SigV4 signing of requests. If not supplied, then environment AWS_REGION will be used.	No
access_key	The AWS Access Key to be used to call the API Endpoint	No
secret_key	The AWS Secret Access Key to be used to call the API Endpoint	No
session_token	The Session Token associated with a temporary STS Token	No
service_endpoint	Allows you to ignore the cached endpoint configuration, and connect your client to a specific endpoint. Intended for testing purposes.	No
tls	Specifies whether TLS is used to connect to the API. Turned on by default, but can be switched off for local testing	No

Calling Client Methods

You can call any of the client methods directly, without considering authentication & authorisation, or HTTP methods and paths.