This repository contains the HTTP API of the MODERATE platform, serving as the public entry point for developers to interact programmatically with the data assets and services provided by MODERATE.

The API is based on the following main building blocks:

• FastAPI as the HTTP API framework.
• SQLModel to define the data models and interact with the database.
• Casbin to implement the authorization layer.

Authentication is handled by the central MODERATE identity provider (Keycloak). The API is prepared to sit behind MODERATE's API gateway (APISIX) which communicates with Keycloak to issue access tokens and then include them in the Authorization header of the requests forwarded to the API. The API then validates the token and extracts the user's identity from it.

Authorization is based on the list of roles assigned to the user in Keycloak, which are then mapped to permissions in the API using Casbin.

Documentation of the API is based on the OpenAPI specification and is automatically generated by FastAPI.

You can deploy a local development instance of the API that includes APISIX and Keycloak in an effort to faithfully reproduce the production environment. There are two options when it comes to the object storage service, the first one is using the built-in local MinIO instance, and the second one is using the S3-compatible interface of a GCS bucket .

To use MinIO:

task dev-up

To use GCS (or any other S3-compatible service):

ACCESS_KEY="TheAccessKey" SECRET_KEY="TheSecretKey" task dev-up-gcs

Other S3-related environment variables such as the region and endpoint can be found in the Taskfile. The default configuration points to the S3-compatible interface of GCS.

You need to create an admin user in Keycloak to be able to log in to the API. Moreover, this user needs to be assigned a specific role. Check the Compose file and .env.dev.default for the URLs and default credentials.

The role name is defined in the moderate_api/config.py file. Please note that this role is a client-level role, and not a realm-level role—the role should be created in the apisix client.

The MODERATE Trust Services are an optional dependency of the platform API. When this dependency is available, the API can use it to check the integrity of datasets via cryptographic proofs stored in the IOTA DLT.

To deploy a development instance of the Trust Services along with the API you need to create a .env.trust.local file that defines the L2_PRIVATE_KEY environment variable. Please check the Trust Services repository for further information.