إنتقل إلى المحتوى الرئيسي

ADR-004: API — GraphQL + REST

Status: Accepted Date: May 2026

Context​

BayanCore serves multiple client types (web, mobile, integrations) with different API needs.

Decision​

Dual API strategy:

  • GraphQL: Primary API for frontend applications (flexible queries, batching)
  • REST: For external integrations, webhooks, and third-party systems

Standards:

  • OpenAPI 3.1 for REST endpoints
  • GraphQL schema with versioned types
  • Authentication via JWT/OAuth2

Consequences​

  • Positive: Best of both worlds, flexible for different use cases
  • Trade-offs: Two APIs to maintain and document
  • Risks: Inconsistency between GraphQL and REST responses

Alternatives Considered​

  • GraphQL Only: Simpler but less compatible with external systems
  • REST Only: Widely compatible but less flexible for frontend