Authentication
The Radiant MLHub API uses API keys to authenticate users. These keys must be passed as a key
query parameter in any request made to the API.
Anyone can register for an API key by going to https://mlhub.earth and creating an account.
Once you have logged into your account, go to the Settings & API keys page at
https://mlhub.earth/profile to create an API key.
Using API Keys
The best way to add your API key to requests is to create a Session
instance using the
get_session()
helper function and making requests using this instance:
>>> from radiant_mlhub import get_session
>>> session = get_session()
>>> r = session.get(...)
You can associate an API key with a session in a number of ways:
programmatically via an instantiation argument
using environment variables
using a named profile
The Session
resolves an API key by trying each of the following (in this order):
Use an
api_key
argument provided during instantiation>>> session = get_session(api_key='myapikey')
Use an
MLHUB_API_KEY
environment variable>>> import os >>> os.environ['MLHUB_API_KEY'] = 'myapikey' >>> session = get_session()
Use a
profile
argument provided during instantiation (see Using Profiles section for details)>>> session = get_session(profile='my-profile')
Use an
MLHUB_PROFILE
environment variable (see Using Profiles section for details)>>> os.environ['MLHUB_PROFILE'] = 'my-profile' >>> session = get_session()
Use the
default
profile (see Using Profiles section for details)>>> session = get_session()
If none of the above strategies results in a valid API key, then an APIKeyNotFound
exception is raised.
The radiant_mlhub.session.Session
instance inherits from requests.Session
and adds a few conveniences to a typical
session:
Adds the API key as a
key
query parameterAdds an
Accept: application/json
headerAdds a
User-Agent
header that contains the package name and version, plus basic system information like the the OS namePrepends the MLHub root URL (
https://api.radiant.earth/mlhub/v1/
) to any request paths without a domainRaises a
radiant_mlhub.exceptions.AuthenticationError
for401 (UNAUTHORIZED)
responses
Using Profiles
Profiles in radiant_mlhub
are inspired by the Named Profiles
used by boto3
and awscli
. These named profiles provide a way to store API keys (and potentially other configuration) on your local system
so that you do not need to explicitly set environment variables or pass in arguments every time you create a session.
All profile configuration must be stored in a .mlhub/profiles
file in your home directory. The profiles
file uses the INI file
structure supported by Python’s configparser
module as described here.
Hint
If you do not have write access to the home directory on your machine, you can change the location of the profiles
file using the MLHUB_HOME
environment variables. For instance, setting MLHUB_HOME=/tmp/some-directory/.mlhub
will cause the client to look for your profiles in a
/tmp/some-directory/.mlhub/profiles
file. You may want to permanently set this environment variable to ensure the client continues to look in
the correct place for your profiles.
The easiest way to configure a profile is using the mlhub configure
CLI tool documented in the CLI Tools section:
$ mlhub configure
API Key: <Enter your API key when prompted>
Wrote profile to /home/user/.mlhub/profiles
Given the following profiles
file…
[default]
api_key = default_api_key
[project1]
api_key = some_other_api_key
[project2]
api_key = yet_another_api_key
These would be the API keys used by sessions created using the various methods described in Using API Keys:
# As long as we haven't set the MLHUB_API_KEY or MLHUB_PROFILE environment variables
# this will pull from the default profile
>>> session = get_session()
>>> session.params['key']
'default_api_key'
# Setting the MLHUB_PROFILE environment variable overrides the default profile
>>> os.environ['MLHUB_PROFILE'] = 'project1'
>>> session = get_session()
>>> session.params['key']
'some_other_api_key'
# Passing the profile argument directly overrides the MLHUB_PROFILE environment variable
>>> session = get_session(profile='profile2')
>>> session.params['key']
'yet_another_api_key'
# Setting the MLHUB_API_KEY environment variable overrides any profile-related arguments
>>> os.environ['MLHUB_API_KEY'] = 'environment_direct'
>>> session = get_session()
>>> session.params['key']
'environment_direct'
# Passing the api_key argument overrides all other strategies or finding the key
>>> session = get_session(api_key='argument_direct')
>>> session.params['key']
'argument_direct'
Making API Requests
Once you have your profiles
file in place, you can create a session that will be used to make authenticated requests to the API:
>>> from radiant_mlhub import get_session
>>> session = get_session()
You can use this session to make authenticated calls to the API. For example, to list all collections:
>>> r = session.get('/collections') # Leading slash is optional
>>> collections = r.json()['collections']
>>> print(len(collections))
47
Relative v. Absolute URLs
Any URLs that do not include a scheme (http://
, https://
) are assumed to be relative to the Radiant MLHub root URL. For instance,
the following code would make a request to https://api.radiant.earth/mlhub/v1/some-endpoint
:
>>> session.get('some-endpoint')
but the following code would make a request to https://example.org
:
>>> session.get('https://example.org')
It is not recommended to make calls to APIs other than the Radiant MLHub API using these sessions.