directus-integration

Directus Integration

Connecting to Directus is about handling contracts: authentication, predictable queries, and consistent errors. Avoid "calling the API without a model" (loose strings) — typing and clear states make consumption reliable.

Objective

• Read and write data from Collections with controlled queries.
• Stay secure: admin tokens never on the client.
• Standardize error handling and states (loading/error/success).

Non-negotiable rules

• Never expose admin/privileged tokens in mobile/browser.
• Use a single client per app/process (singleton) with base URL and interceptors.
• Always handle HTTP errors + Directus messages; do not swallow failures.
• Separate the "data contract" (DTOs/types) from the UI code.

Integration via API (HTTP)

Consumption pattern:

1. Authn → obtain an Access Token (or use the user's token).
2. Query → GET /items/<collection> with:
   • fields (the minimum necessary)
   • filter and sort
   • limit + pagination (page, or cursor according to your pattern)
   • deep only when you need relations
3. Mutation → POST/PATCH/DELETE with a validated payload.

Integration via SDK (recommended)

If the project uses the Directus SDK (e.g., @directus/sdk):

• Create a single directusClient layer with:
  • base URL
  • refresh strategy (if necessary)
  • timeout/retry for transient failures
• Centralize "response mapping" to your domain DTOs.

Queries and projections

• Prefer "lean fields" to reduce payload and cost.
• Avoid deep deep without necessity (latency and complexity).
• In lists: paginate and filter on the server.
• In detail: use fields with the essentials and specific relations.

Error handling (contract)

Map errors to categories:

• 401/403 → authentication/authorizations (session handling)
• 404 → resource does not exist
• 409 → version/concurrency conflict (if applicable to your flow)
• 422 → validation (fields with messages)
• 5xx → internal error (fallback + log)

Rule: messages for the UI must be human; internal details go to logs.

Security

• Configure CORS and Directus-side rules to the minimum necessary.
• For sensitive endpoints, validate ownership/role on the backend (not just on the client).
• If there are uploads, use the directus-files skill (do not mix logic here).

Integration with other skills

• Modeling: directus-data-modeling
• Permissions: directus-auth-permissions
• Extensions: directus-extensions
• Files: directus-files
• Deploy/migrations: directus-migrations-import-export

Completion criteria

• Client with secure authentication and standardized error
• Lean queries (fields) and correct pagination
• DTOs/types present where it makes sense
• No privileged tokens in the client