Document usage of the SDK against Preview

[sirosen]

This runs much deeper than #236.
We need to document usage, including, but not limited to:

• Preview client registration
• Preview identities/endpoints/entities being distinct from their Production counterparts, and the absence of any magic or automatic mirroring
• Setting up recommended patterns for doing environment dispatch to get at Preview (i.e. you might want a single codebase, but multiple client IDs wrapped in an env var check)

[ajsierakowski]

Any chance you can provide a quick and dirty intro on how to force globus-sdk-python to use the preview environment? I've just realized that I'm having trouble testing the preview environment because the sdk keeps using the production auth api.

Thanks!

[sirosen]

@ajsierakowski for right now, you can do the following:

• register your client at auth.preview.globus.org/developers and make it as similar to your production client as possible
• set the GLOBUS_SDK_ENVIRONMENT=preview environment variable before running SDK code

That environment variable will tell the SDK to use the Preview Auth and Transfer APIs.

If you're having trouble, I'd also recommend:

• check that you're using the Client ID for your Preview client
• try turning on debug logging for the SDK (more on this below)

For debug logging, you need to use python logging. As a simple example,

import logging
l = logging.getLogger('globus_sdk')
l.setLevel(logging.DEBUG)
l.addHandler(logging.StreamHandler())

Fair warning: we've made SDK debug logging really chatty, but it includes details like

Request made to URL: https://transfer.api.preview.globus.org/v0.10/delete

which can be helpful when troubleshooting.

Something which I've found helpful in the past, and you may too, is to actually have your client code detect GLOBUS_SDK_ENVIRONMENT like so:

client_id = 'production_client_id'
if os.environ.get('GLOBUS_SDK_ENVIRONMENT') == 'preview':
    client_id = 'preview_client_id'
native_auth_client = NativeAppAuthClient(client_id)

Hope this all helps (and helps us write docs on this topic).

[ajsierakowski]

Thanks for the clear description. The environment variable was precisely what I needed.