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

API Design

Overview​

BayanCore exposes a dual API strategy: GraphQL for frontend applications and REST for external integrations.

GraphQL API​

Schema Organization​

schema/
├── types/          # GraphQL type definitions
├── queries/        # Read operations
├── mutations/      # Write operations
└── subscriptions/  # Real-time updates

Naming Conventions​

  • Types: PascalCase (e.g., Invoice, WorkflowInstance)
  • Queries: camelCase (e.g., getInvoice, listWorkflows)
  • Mutations: camelCase with verb prefix (e.g., createInvoice, updateWorkflow)

REST API​

Endpoint Structure​

/api/v1/
├── /invoices/          # Invoice CRUD
├── /workflows/         # Workflow management
├── /compliance/        # ZATCA, PDPL endpoints
└── /integrations/      # Third-party webhooks

Standards​

  • OpenAPI 3.1 specification
  • JSON:API response format
  • Pagination: cursor-based
  • Versioning: URL path (/v1/, /v2/)

Authentication​

  • JWT tokens via Clerk
  • API keys for external integrations
  • OAuth2 for third-party access

Error Handling​

  • Standard error response format
  • HTTP status codes per RFC 7807
  • Detailed error messages for debugging