Integration and Automation
The GUARDARA API allows performing all the functionalities available via the user interface in a programmatic way. It can be used to integrate GUARDARA into your CI/CD pipeline or to integrate with any 3rd-party solution.
Accessing the API
The API is accessible over HTTPS on port 8443, under the /api URI. Requests made to the API must be authenticated using an API Key.
Follow the instructions below to create a new API key.
- Go to the API Keys tab of the Settings page
- Click the + button on the top-left corner of the screen
- Assign one or more Scopes to the API key using the Scopes dropdown menu
- Configure when the API key should expire (the default is 1 month)
- Save the API key by clicking on the Save button
Scopes define what actions can be performed using the API key. Only Scopes that were assigned to the user’s account can be granted to API keys. For example, if a user has been only authorized to obtain a list of engines (engine:read scope), the Scope list on the API key form will only show this single Scope item. Visit the Scopes section of the Access Control documentation to learn more about the available Scopes.
Once an API key is created, the API Key will be presented to the user. This key must be provided in each API request. Make sure to save the API key to a safe location as it will not be shown again.
Authentication
Each API request is authenticated, requiring the API key to be included in the requests as a Bearer token. An example request using curl can be seen below.
curl "https://127.0.0.1:8443/api/template/group/root" \
-H "Authorization: Bearer ${API_KEY_HERE}" \
-H "Connection: close"
API Endpoints
The User Interface is a frontend for the GUARDARA API that also serves as the documentation for the API. You can use your web browser's developer tools to see the network requests sent by the User Interface to the API to learn how to use the API.
The authentication method is the only difference between the requests sent by the User Interface and the requests you would send, for example, from a CI/CD pipeline. Always use an API Key and send it as a Bearer token to authenticate to the API.
Python API
The GUARDARA Python API allows performing all the actions that are available via the user interface straight from Python. Behind the scenes the Python API performs calls to the API exposed by the GUARDARA Manager. The Python API is part of the GUARDARA SDK, which you can download from the Settings > Developers page of the Manager. Refer to the GUARDARA SDK section of the Developer's Guide to learn how to install and configure the SDK.
You can find a few examples on how you can use the Python API on GitLab.
Creating a Session
To be able to access the GUARDARA features a session has to be configured as shown below.
#!/usr/bin/env python3
from guardara.api import Session
session = Session(
"127.0.0.1",
8443,
api_key,
cert_verify=False,
)
You can find an example of how to fetch the list of Message Templates using the Python API on GitLab.
Low-level API Calls
We are gradually extending the Python API. If a feature is not implemented in a user-friendly way, it can still be accessed by performing direct calls to the Manager API. The following methods are exposed to do that:
session.connection.fetch(service, resource, headers={})
session.connection.create(service, resource, data, headers={})
session.connection.update(service, resource, data, headers={})
session.connection.remove(service, resource, headers={})
The methods above expect the name of the microservice to communicate with via the service argument. For example, if we wanted to interact with the Template service, the value of the service argument would be template.
The resource argument is the type of resource handled by the service. For example, in case of the template service you could use /message, /flow, /callback, /collection and /project as the resource. For example, to fetch the message with ID b279f41c-c905-4da3-a4ee-b8744bcd86a4 you would:
(response_code, data) = session.connection.fetch("template", f"/message/{MESSAGE_ID}")
The response is a tuple. The first item is the response code, the second item is the data received.
Examples
You can find more examples on GitLab. If you have an example in mind you would like to see, feel free to open a new issue for the project.