MaIS Client Configuration

To begin using any of the MaIS API clients, you must first instantiate a MAISClient. This stores configuration common to all clients.

class stanford.mais.client.MAISClient(urls: Mapping[str, str], cert: pathlib.Path, _default_timeout: Tuple[float, float] = (3.0, 3.0))[source]

The MAISClient is the first thing you will instantiate when you want to interact with a MaIS API.

To instantiate a MAISClient, you will need to provide two pieces of configuration as parameters to the class constructor. The configuration items are documented below.

For convenience, you may wish to use one of the ready-made constructors, MAISClient.prod() and MAISClient.uat(). If you use one of those, you need only provide a client certificate path.

urls: Mapping[str, str]

A mapping of API to URL.

This mapping uses API names (like account) as keys, and the base URL as the value.

If you are setting up your own client instance, you will need to provide entries for each API you plan on using. If you are using the UAT or PROD (production) environments, you can call uat() or prod(). If you are using a different environment, or developing a MaIS API locally, you won’t be able to use those methods, but you can study the code (more specifically, the URLs they embed) to get an idea of which URL is needed for which service.

Raises

TypeError – You did not provide a mapping.

cert: pathlib.Path

The path to a TLS client key & cert.

This must refer to a single file. The file must be in PEM format (the text format), and must have a single key followed by a certificate. If the key is an EC key, then any necessary EC parameters may be included, before the private key. This is the same format that most programs (particularly web servers) use, when you give them the server key & certificate in a single file.

Warning

The private key must not be password-protected. Enabling support for this is covered in https://github.com/psf/requests/issues/1573.

A test load of the key and certificate will be made before the constructor completes.

Raises

  • FileNotFoundError – The file does not exist.

  • PermissionError – We do not have read permission on the file.

  • ssl.SSLError – The private key and certificate do not match, or there was some other problem loading the certificate.

classmethod prod(cert: pathlib.Path) → stanford.mais.client.MAISClient[source]

Return a client configured to connect to connect to production (PROD) APIs.

The returned client has all of the URLs pre-configured.

Note

A new client instance is created every time you call this. If you want to take advantage of caching, call this only once per thread/process.

Parameters

cert – The path to a file containing a client key & cert. It must be provisioned by MaIS to operate in the PROD environment.

Raises

  • FileNotFoundError – The file does not exist.

  • PermissionError – We do not have read permission on the file.

  • ssl.SSLError – The private key and certificate do not match, or there was some other problem loading the certificate.

classmethod uat(cert: pathlib.Path) → stanford.mais.client.MAISClient[source]

Return a client configured to connect to connect to UAT APIs.

The returned client has all of the URLs pre-configured.

Note

A new client instance is created every time you call this. If you want to take advantage of caching, call this only once per thread/process.

Parameters

cert – The path to a file containing a client key & cert. It must be provisioned by MaIS to operate in the UAT environment.

Raises

  • FileNotFoundError – The file does not exist.

  • PermissionError – We do not have read permission on the file.

  • ssl.SSLError – The private key and certificate do not match, or there was some other problem loading the certificate.

session() → requests.sessions.Session[source]

Create a Requests session container.

This is a Requests Session instance, which has the certificate and timeouts pre-configured. All that remains is to set appropriate ‘Accept’ and ‘Content-Type’ headers, and it will be ready for use.

Note

A new container is created each time you call this. If you want to take advantage of caching, call this once per thread/process.