AimableDocs
DocsAPI Reference

Tenant Models

Introduction to Tenant Models

The "tenant-models" domain in the FastAPI API allows you to manage models specific to individual tenants within a multi-tenant architecture. This capability is crucial for applications that need to maintain separate configurations or data models for different clients or organizational units. By leveraging tenant models, you can ensure data isolation, customization, and scalability across various tenants in your application.

Key Concepts

Tenant Model

A tenant model represents the data structure or configuration specific to a tenant. It is identified by a unique tenant_model_id and can be created, retrieved, updated, or deleted using the provided API endpoints.

Idempotency

When creating a tenant model, an Idempotency-Key is required to ensure that repeated requests do not result in duplicate models. This key allows the server to recognize and ignore duplicate requests, providing a reliable way to handle network retries.

Authentication

Most endpoints in this domain support an optional X-API-Key header for authentication. This key is used to verify the identity of the client and authorize access to the API.

Common Workflows

Listing Tenant Models

To list tenant models, use the GET /v1/tenant/models endpoint. This endpoint supports pagination through the limit and cursor query parameters, allowing you to navigate through large sets of models efficiently.

curl -X GET "https://api.example.com/v1/tenant/models?limit=10&cursor=abc123" -H "X-API-Key: your_api_key"

Creating a Tenant Model

To create a new tenant model, send a POST request to /v1/tenant/models with the required Idempotency-Key header and a JSON body containing the model details.

curl -X POST "https://api.example.com/v1/tenant/models" \
-H "Idempotency-Key: unique_key" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"name": "New Tenant Model", "description": "Description of the model"}'

Retrieving a Tenant Model

To fetch details of a specific tenant model, use the GET /v1/tenant/models/{tenant_model_id} endpoint.

curl -X GET "https://api.example.com/v1/tenant/models/tenant_model_id" -H "X-API-Key: your_api_key"

Updating a Tenant Model

To update an existing tenant model, send a PATCH request to /v1/tenant/models/{tenant_model_id} with the updated data in the request body.

curl -X PATCH "https://api.example.com/v1/tenant/models/tenant_model_id" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"name": "Updated Tenant Model"}'

Deleting a Tenant Model

To delete a tenant model, use the DELETE /v1/tenant/models/{tenant_model_id} endpoint.

curl -X DELETE "https://api.example.com/v1/tenant/models/tenant_model_id" -H "X-API-Key: your_api_key"

Important Considerations

  • Authentication: While the X-API-Key is optional, it is recommended to use it for secure access to the API.
  • Pagination: Use the limit and cursor parameters to handle large datasets efficiently.
  • Error Handling: Implement appropriate error handling to manage network issues and server errors. Check for HTTP status codes and handle them accordingly.
  • Idempotency: Ensure that the Idempotency-Key is unique for each create request to avoid unintended duplicate models.

By understanding these concepts and workflows, you can effectively manage tenant models within your application, ensuring data isolation and customization for each tenant.