New_Micro_Learning/docs/api-guidelines.md

API Guidelines

• Base path: /api/v1
• JSON request and response bodies
• Resource identifiers are opaque strings
• ISO 8601 UTC timestamps at boundaries
• Locale and timezone are explicit request context
• Cursor pagination for high-volume feeds; page pagination where users need page counts
• Filter and sort fields are allow-listed
• Mutations support idempotency keys where duplicate execution is costly

Response envelope

{
  "data": {},
  "meta": { "requestId": "..." }
}

Validation errors use a stable machine code, localized user-safe message, and field errors. Authorization must not leak cross-tenant existence. Controllers delegate to application commands and queries.

Taxonomy endpoints

taxonomy-types, taxonomy-nodes, taxonomy-relationships, content-mappings, mapping-suggestions, evidence, capabilities, capability-snapshots, skill-expectations, skill-gaps, and content-coverage live under /api/v1 and are policy protected.