Jebena Client for Python

This package implements a simple python client for accessing the Jebena server. Our client handles basic retry logic and error handling, and supports usage via both command-line and importing in python code.

Requires Python 3.8 or newer, and nothing outside the standard library.

Usage

1. Create your API Key on your Jebena server. You will need all three parts (JEBENA_API_ENDPOINT, JEBENA_API_KEY_NAME, and JEBENA_API_SECRET_KEY).

   1. Log in via web browser, and go to the upper-right user menu. Select "Manage API Keys" and follow the instructions there to create your key. If you need write-access, make sure to enable writes for the API key.

   2. Store your API key securely! Anyone who has access to your API Keys can access and modify data as though they were you. API Keys should not be shared with other users; they should create their own API keys.

      • On MacOS: create an encrypted disk image using Disk Utility (File -> New Image -> Blank Image; set Encryption to 256-bit). Inside it create a file name ./jebena-keys.sh. Edit the file to have your API values like below. You can then source /Volumes/<disk-name>/jebena-keys.sh to load your API keys into a shell when you need. (If you reboot, re-open the .img file to re-mount the encrypted disk image.)

        export JEBENA_API_KEY_NAME=jeb00000...
        export JEBENA_API_SECRET_KEY=<sensitive>
        export JEBENA_API_ENDPOINT=https://api-hostname.example.com/v1/
        

2. Install the jebenaclient package. There are two different methods for this.

   • pip method: If you have a virtualenv, run pip install https://github.com/jebena/jebena-python-client/archive/main.zip
   • .py file method: Alternatively, you can directly snag this .py file, which can then be checked into your own repo.

     curl -o jebenaclient.py https://github.com/ghraw/jebena/jebena-python-client/main/jebenaclient/jebenaclient.py
     chmod +x jebenaclient.py
     

3. Run your GQL query — either via command line or via python code. Remember to source /path/to/jebena-keys.sh in your shell first. For documentation on GQL schema, visit the URL given in your JEBENA_API_ENDPOINT, click GraphiQL, and on the right side, expand "< Docs".

   • Command line method: for pip, run python3 -m jebenaclient; for .py file, run ./jebenaclient.py and then enter your query at the prompt.

     • If your query is in a file, you can pipe your query in:
       • cat some-query.txt | python3 -m jebenaclient
       • echo "query { me { person { displayName } } }" | python3 -m jebenaclient

   • Python code method: import the client and call jebenaclient.run_query (see below for additional details).

     import logging
     import jebenaclient
     
     LOGGER = logging.getLogger(__name__)
     
     try:
        results = jebenaclient.run_query("query { me { person { displayName } } }")
        print(results['data']['me']['person']['displayName'])
     except jebenaclient.JebenaCliGQLException as exc:
        LOGGER.error("The query was invalid (%s)", exc)
     except jebenaclient.JebenaCliException as exc:
        LOGGER.error("The request could not be processed (%s).", exc)
     

Passing GQL Variables

There are two ways to pass variables in your query: programmatically or via wrapped query.

Programmatically in function call. This method only applies to python code.

import jebenaclient
example_query = "query theQuery($someUUID: String!) { project(uuid: $someUUID) { name shortName } }"
example_variables = {
    "someUUID":"c893bf7f-2bb0-e153-c2a2-6699b847e584"
}
response = jebenaclient.run_query(example_query, variables=example_variables)
print(response["data"]["project"])

Wrapped Query Method. Your GQL query can include both query and variable keys, for a "wrapped" query.

For example, in the shell (the "heredoc" can be replaced with a file, e.g. cat query.txt | ./jebenaclient.py):

source /path/to/jebena-keys.sh
cat <<'EOF' | ./jebenaclient.py
{
  "query": "query theQuery($someUUID: String!) { project(uuid: $someUUID) { name shortName } }",
  "variables": {
    "someUUID":"c893bf7f-2bb0-e153-c2a2-6699b847e584"
  }
}
EOF

The same example, as python code:

import jebenaclient
example_query = '''
{
  "query": "query theQuery($someUUID: String!) { project(uuid: $someUUID) { name shortName } }",
  "variables": {
    "someUUID":"c893bf7f-2bb0-e153-c2a2-6699b847e584"
  }
}
'''
response = jebenaclient.run_query(example_query)
print(response["data"]["project"])

Setting API keys programmatically

The run_query() function accepts these optional parameters for use cases where loading secrets in the ENV is not practical.

• api_endpoint: The URL of your Jebena API server. When not passed, the ENV variable JEBENA_API_ENDPOINT is accessed.

• api_key_name: Your Jebena API key name. When not passed, the ENV variable JEBENA_API_KEY_NAME is accessed. This value is not sensitive.

• api_secret_key: The secret key associated with your API key name. When not passed, ENV variable JEBENA_API_SECRET_KEY is read. This value must be kept securely stored!

Retries and timeouts

Failed queries are retried a few times. Mutations are retried only on errors known to have been raised before the server ran any application logic, since a mutation that reached the server may already have applied and re-sending it risks a duplicate write. Pass allow_retries_on_mutations=True to retry regardless, but only for mutations you know are idempotent. When the server sends a Retry-After, that sets the delay.

JEBENA_CLIENT_TIMEOUT (default 300 seconds) is the socket timeout applied to each attempt. It bounds inactivity rather than total transfer time, so a server that trickles a response slowly can exceed it; the command-line entry point has a separate watchdog on total run time.

Working with Jebena Trace IDs

The Jebena API Server provides a "Jebena Trace ID" that can be used for tracing the backend server's logs for any given request. This is provided as an HTTP header to clients.

Calling jebenaclient.get_last_run_trace_id() after a call to jebenaclient.run_query() will provide that call's Jebena Trace ID, which can then be used by server developers (e.g. jebena aws logs trace <id>). It is None when the server did not return one.