Service architecture

The Managed Cloud API provides two modes of operation, synchronous (requiring a single container) and asynchronous (requiring multiple containers). The synchronous API differs from the cloud API, in that requests are immediately processed, and the PDF is returned directly in the response. The asynchronous API is identical to the cloud API, with tasks entering a queue to be processed and the PDFs needing to be retrieved once the task status indicates completion.

Synchronous API

The deployment of the synchronous API involves a single container.

Asynchronous API

The asynchronous API requires 3 containers at minimum, one container for the API, one container for the worker which generates the PDFs, and lastly one container for a Redis database instance (you may use your own Redis instance if preferred).

The worker container can be scaled up with multiple instances to enable concurrency.

Licence activation

The private deployment of this API requires activation from the licence server once a day. This is performed using a HTTP GET request to the licence server, which returns a 24-hour access token. Once this expires, it will automatically be renewed in the background, when a request is made to the deployed API.

To be able to activate your licence, the environment variable HYBISCUS_API_KEY must be set in the API container, using an API key created in the Hybiscus dashboard.

No usage data, tracking data or any other kind of data, apart from your deployed version, is collected from your privately deployed API to the Hybiscus servers. Licence activation involves ONLY supplying the Hybiscus servers with your API key and deployed version, to confirm subscription.

API usage and access

The provided API provides two modes of operation – synchronous and asynchronous.

The asynchronous API is identical to the cloud-based API, where tasks enter a queue to be processed. The synchronous API differs from the cloud API, in that all requests are synchronous. This means the responses from the build and preview report endpoints will contain the PDF, instead of a task ID.

Endpoints

The privately deployed API provides the following endpoints:

Synchronous endpoints

• /api/v1/sync/build-report
• /api/v1/sync/preview-report

Asynchronous endpoints

These endpoints are only available if async mode is enabled in your deployment.

• /api/v1/async/build-report
• /api/v1/async/get-task-status
• /api/v1/async/get-report

The asynchronous endpoints are identical to the cloud API.

Similar to the cloud API, you can also directly visit the domain of your privately deployed API and view interactive documentation powered by Redocly or Swagger UI.

Authentication

Authentication is performed in the same way as with the cloud API, using either a HTTP header or a URL query param. There is only one API key that is valid for your deployment.

The API key used to authenticate your requests to your privately deployed API is set via the environment variable API_KEY.

Cloud Editor

As of

, the Cloud Editor is also available in the Docker image. It can be accessed at /cloud-editor. As the endpoint is not protected (this should be handled by a reverse proxy or your cloud provider), using the Cloud Editor requires inputting the API key for your Managed Cloud deployment (this is separate from your Hybiscus Cloud API key).

The Cloud Editor in the Managed Cloud also supports using the synchronous or asynchronous API endpoints, to support both modes of deployment for the Managed Cloud API.

Maintenance and updates

Your private deployment of the API is powered by an image stored in our private container registry on Microsoft Azure. The underlying software serving both our cloud and private deployment APIs is common, and thus any new features released on our cloud offering will be made available to you as well.

To avail these new features, you will need to update your private deployment to the latest version. To see what new features are available, check the What's new page.