Collection Connectors

Introduction to Collection-Connectors

The "collection-connectors" domain in the FastAPI API allows you to manage connectors within specific collections in a space. Connectors are integral for linking collections to external data sources or systems, enabling seamless data integration and synchronization. This functionality is crucial for applications that require dynamic data interaction across multiple platforms.

Key Concepts and Entities

• Space: A logical grouping of collections. Each space is identified by a unique space_id.
• Collection: A subset within a space that holds data. Identified by a collection_id.
• Connector: An entity that facilitates data exchange between a collection and an external source. Identified by a connector_id.
• Sync: A process that synchronizes data between the collection and the connected source. Each sync operation can be tracked with a sync_id.

Common Workflows

Listing and Managing Connectors

To manage connectors within a collection, you typically start by listing existing connectors, creating new ones, or updating existing configurations.

1. List Connectors: Retrieve a list of connectors for a specific collection.

   curl -X GET "https://api.example.com/v1/spaces/{space_id}/collections/{collection_id}/connectors" -H "X-API-Key: your_api_key"

2. Create a Connector: Add a new connector to a collection.

   curl -X POST "https://api.example.com/v1/spaces/{space_id}/collections/{collection_id}/connectors" \
   -H "Idempotency-Key: unique_key" \
   -H "Content-Type: application/json" \
   -d '{"name": "New Connector", "type": "external_source"}'

3. Update a Connector: Modify an existing connector's configuration.

   curl -X PATCH "https://api.example.com/v1/spaces/{space_id}/collections/{collection_id}/connectors/{connector_id}" \
   -H "Content-Type: application/json" \
   -d '{"name": "Updated Connector Name"}'

4. Delete a Connector: Remove a connector from the collection.

   curl -X DELETE "https://api.example.com/v1/spaces/{space_id}/collections/{collection_id}/connectors/{connector_id}" \
   -H "X-API-Key: your_api_key"

Synchronizing Data

Synchronization is key to keeping data up-to-date between your collection and external sources.

1. Trigger a Sync: Initiate a synchronization process for a connector.

   curl -X POST "https://api.example.com/v1/spaces/{space_id}/collections/{collection_id}/connectors/{connector_id}/sync" \
   -H "Content-Type: application/json"

2. List Syncs: View all sync operations for a connector.

   curl -X GET "https://api.example.com/v1/spaces/{space_id}/collections/{collection_id}/connectors/{connector_id}/sync" \
   -H "X-API-Key: your_api_key"

3. Cancel a Sync: Stop an ongoing sync operation.

   curl -X POST "https://api.example.com/v1/spaces/{space_id}/collections/{collection_id}/connectors/{connector_id}/sync/cancel" \
   -H "X-API-Key: your_api_key"

Important Considerations

• Authentication: Most endpoints require an X-API-Key for authentication. Ensure your requests include this header.
• Idempotency: When creating connectors, use the Idempotency-Key header to prevent duplicate operations.
• Pagination: Use limit and cursor query parameters when listing connectors or syncs to handle large datasets efficiently.
• Error Handling: Handle HTTP errors gracefully. Check response codes and messages to debug issues.

By understanding and utilizing these endpoints, you can effectively manage data integrations within your applications, ensuring robust and scalable data operations.