tapi

README

tapi

This tool will allow easy command-line access to many features of the Tidepool API. It currently has limited features, but additional features will be added over time.

NB: If you would like to use this tool on the Tidepool platform running on your machine (i.e., localhost), please note the following additional instructions:

• make sure you're running the data services (for instructions see the repo README, and don't forget to . ./env.sh)
• from the root of your platform repo directory, use the full path wherever you see tapi in the shell commands below (e.g., $ _bin/tools/tapi/tapi login)

Which Server?

This tool must be configured with the appropriate HTTP endpoint in order to communicate with the Tidepool API. You can specify either the endpoint directly, or the Tidepool environment name and the endpoint will be determine automatically. It is recommended that you use specify the Tidepool environment name rather than the endpoint.

Note: The endpoint takes precedence over the environment name.

Environment

If you choose to specify the Tidepool environment name when invoking the tool it will automatically convert from all known environments (ie. prd, int, stg, dev, local) to the appropriate endpoint. For example:

$ tapi login --env=prd

TIDEPOOL_ENV

Rather than specifying the --env argument on every command, you may define the TIDEPOOL_ENV environment variable. All subsequent invocations of the tool will use the environment specified in the TIDEPOOL_ENV environment variable. For example:

$ export TIDEPOOL_ENV=prd
$ tapi login

Note: The command line argument takes precedence over the environment variable.

Endpoint

Alternatively, you may choose the specify the HTTP endpoint directly. For example:

tapi login --endpoint=https://api.tidepool.org

TIDEPOOL_ENDPOINT

Rather than specifying the --endpoint argument on every command, you may define the TIDEPOOL_ENDPOINT environment variable. All subsequent invocations of the tool will use the endpoint specified in the TIDEPOOL_ENDPOINT environment variable. For example:

$ export TIDEPOOL_ENDPOINT=https://api.tidepool.org
$ tapi login

Note: The command line argument takes precedence over the environment variable.

Who Are You?

You must authenticate with the Tidepool API in order to use most features of the tool. Once authenticated, the Tidepool session will be stored for future invocations of the tool. (For the curious, the Tidepool session is persisted in ~/.tidepool/session.)

User

To authenticate as a user:

$ tapi login
Email: your-email@domain.com
Password: ********
Logged in.

Alternatively:

$ tapi login --email your-email@domain.com
Password: ********
Logged in.

Server

To use the tool on a Tidepool server instance, authenticate with the server login:

$ tapi server-login

Note: The TIDEPOOL_USER_CLIENT_SERVERTOKENSECRET environment variable must be set as appropriate.

Additional

To logout and destroy the Tidepool session:

$ tapi logout
Logged out.

To verify the Tidepool session with the Tidepool API:

$ tapi whoami
{"isserver":false,"userid":"1234567890"}

Which User?

Many of the Tidepool APIs operate on a particular user, specified via id. Therefore, many of the tool commands include a --user-id argument.

If you are authenticated as a user, then this argument is optional. If not specified, the user id associated with the current Tidepool session will be used.

If you are authenticated on a Tidepool server instance, then this argument is required. A Tidepool server session is not associated with any specific user.

Features

To keep the following examples as succinct as possible, it is assumed that the tool has been previously authenticated with a user account and the --user-id argument is not specified.

Data Set

This tool can manage data sets.

List

To list all data sets for a user:

$ tapi data-set list
(... output ...)

Filter

You may provide limited filtering of the data sets.

Deleted

Data sets that have been previously deleted are not normally included in the list of data sets. If you wish to include deleted data sets in the list, then specify the --deleted argument. For example:

$ tapi data-set list --deleted
(... output ...)

Pagination

By default, the Tidepool API returns data sets in pages with a default and maximum pages size of 100. To effectively list all data sets you will need to specify the --page and --size arguments to interate through all of the available data sets. For example:

$ tapi data-set list --size 50 --page 0
(... first 50 data sets ...)
$ tapi data-set list --size 50 --page 1
(... second 50 data sets ...)

The --size argument can be from 1 to 100. The --page argument can be zero or more.

The last page will either contain less than size number of data sets or will be empty.

Delete

To delete a specific data set, determine its data set id, also known as uploadId, via the list command above, and then invoke the delete data set command. For example:

$ tapi data-set delete --data-set-id ff2346e5623914b1234565661f093459
Data set deleted.

NB: Older upload IDs (from ingestion through the legacy "jellyfish" ingestion service) begin with upid_ and contain only 12 characters in the hash.

Help

For general help with the tool:

$ tapi --help

For more detailed help with a specific command:

$ tapi <command> --help

Replace <command> with one of the top-level commands.

For more detailed help with a specific sub-command:

$ tapi <command> <sub-command> --help

Replace <command> with one of the top-level commands and <sub-command> with a sub-command.

For example:

$ tapi data-set list --help
NAME:
   tapi data set list - list data sets

USAGE:
   tapi data-set list [command options] [arguments...]

OPTIONS:
   --user-id USERID     USERID of the user to list data sets
   --deleted            include deleted data sets in the list
   --page PAGE          pagination PAGE (default: 0)
   --size SIZE          pagination SIZE (default: 0)
   --endpoint ENDPOINT  Tidepool API ENDPOINT (eg. 'https://api.tidepool.org') [$TIDEPOOL_ENDPOINT]
   --env ENVIRONMENT    Tidepool ENVIRONMENT (ie. 'prd', 'int', 'stg', 'dev', 'local') [$TIDEPOOL_ENV]
   --proxy URL          proxy URL [$HTTP_PROXY]
   --pretty, -p         pretty print JSON
   --verbose, -v        include info output