OpenAPI-Common 2.0.0#

Introduction#

OpenAPI-Common is part of the larger PyAnsys effort to facilitate the use of Ansys technologies directly from Python.

Because some Ansys products expose HTTP APIs rather than gRPC APIs, this Python library provides a common client to consume HTTP APIs, minimizing overhead and reducing code duplication.

Background#

A widely used standard for HTTP REST-style APIs is the OpenAPI standard, formerly known as Swagger. OpenAPI-Common is designed to be used alongside code generation tools to produce client libraries for HTTP APIs.

Brief example#

This brief example demonstrates how the client works:

>>> from ansys.openapi.common import ApiClientFactory
>>> client = ApiClientFactory("https://my-api.com")
...          .with_autologon()
...          .connect()
>>> print(client)

<ApiClient url: http://my-api.com>

The client is now ready and available for use with an OpenAPI client.

Authentication schemes#

OpenAPI-Common supports API servers configured with no authentication, API keys, client certificates, and basic authentication.

Windows users can also use Windows Integrated Authentication to connect to Kerberos-enabled APIs with their Windows credentials and to NTLM where it is supported.

Linux users can make use of Kerberos authentication via the [linux-kerberos] extra. This requires a working installation of either MIT Kerberos or Heimdal, as well as some platform-specific build steps. An additional requirement is a correctly configured krb5.keytab file on your system.

Windows and Linux users can authenticate with OIDC-enabled APIs by using the [oidc] extra. Currently only the Authorization Code authentication flow is supported.

Authentication methods by platform#

Authentication method

Windows

Linux

Builder method

API Key

✔️

✔️

.with_anonymous() [1]

Basic

✔️

✔️

.with_credentials()

NTLM

✔️

❌

.with_credentials()

Kerberos

✔️

➕ [2]

.with_autologon()

OIDC

➕ [3]

➕ [3]

.with_oidc()

Advanced features#

You can set all options that are available in Python library requests through the client. This enables you to configure custom SSL certificate validation, send client certificates if your API server requires them, and configure many other options.

For example, to send a client certificate with every request:

>>> from ansys.openapi.common import SessionConfiguration
>>> configuration = SessionConfiguration(
...    client_cert_path='./my-client-cert.pem',
...    client_cert_key='secret-key'
... )
>>> client.configuration = configuration

Platform-specific Kerberos configuration#

Kerberos authentication should be supported wherever the MIT or Heimdal Kerberos client can be installed. OpenAPI-Common has been tested on the platforms that follow. If you manage to use it on another platform, consider contributing installation steps for your platform by making a pull request.

Ubuntu 20.04#

Ubuntu requires the gssapi Python module to be built from source. This requires the Kerberos headers, Python headers for the version of Python that you are using, and a supported compiler. (GCC works well.)

You should then be able to install this module with the [linux-kerberos] extra:

sudo apt install build-essentials python3.8-dev libkrb5-dev
pip install ansys-openapi-common[linux-kerberos]

Once the installation completes, ensure that your krb5.conf file is set up correctly for your Kerberos configuration and that you have a valid keytab file, which is normally in /etc/krb5.keytab.

API reference#

For comprehensive API documentation, see API reference.

Contributions#

Contributions to this library are welcome. For more information, see Contribute.

Project index#