• HTTPS is mandatory for all environments.
• HTTP (unencrypted) must either: Redirect (301/308) to HTTPS in public environments, or be disabled entirely.

Indicative structure (actual hostnames decided at deployment time):

Every endpoint must be prefixed with an explicit version:

No unversioned endpoints are allowed for business-critical resources. Future versions: v2, v3, … following parallel structure.

Backwards compatible changes (additive) do not require a new major version:

• Adding optional fields
• Adding new endpoints
• Adding new enum values with documented default behaviors

Breaking changes require a new version (e.g., /api/v2/...):

• Removing fields
• Renaming fields or endpoints
• Changing response structure in a non-additive way
• Changing semantics of existing behavior

For each breaking change: Keep old version (e.g., v1) alive for a deprecation window (suggested: 6–12 months). Document change summary in changelog and future-expansion-and-roadmap.md.

Clients (Web / Mobile / Provider) should: Target specific versions in their clients, avoid relying on undocumented behaviors.

Pluralized, lower-kebab or lower-snake in URLs, with plural nouns:

Resource names must match domain entities defined in 03-domain-model/domain-entities-and-relationships.md.

Standard REST mapping:

Non-CRUD actions (e.g., confirm booking, cancel booking, launch campaign) should be exposed as sub-resources or action endpoints:

All API requests and responses must use:

File upload endpoints (images, attachments) may use multipart/form-data and must be documented explicitly per endpoint.

• Encoding: UTF-8 only.
• Arabic labels / values (e.g., status labels like "ملغاه") are allowed in response fields intended for UI display (e.g., ui_label_ar).
• System-level enums stay in English (UPPER_SNAKE), see 00-guidelines/naming-conventions.md.

JSON fields: snake_case:

No camelCase or mixed styles.

Single resource:

{
  "data": {
    "...": "..."
  }
}

Collection:

{
  "data": [
    { "...": "..." },
    { "...": "..." }
  ],
  "meta": {
    "total": 120,
    "per_page": 20,
    "current_page": 1,
    "last_page": 6
  }
}

• page: 1-based index.
• per_page: between 10 and 100 by default (configurable per module).

{
  "meta": {
    "total": 120,
    "per_page": 20,
    "current_page": 1,
    "last_page": 6
  }
}

Query parameters used for filtering must be explicit and documented in each module's API file.

All date filters use ISO 8601 (YYYY-MM-DD or full timestamp where needed).

• field for ascending
• -field for descending

Allowed sort fields must be explicitly whitelisted per endpoint.

Backend: Node.js. Supported mechanisms: JWT (bearer tokens in headers):

Session-based auth may be used for Admin Panel / Provider web flows but is out of scope for public API contracts.

Every authenticated request is associated with a User and possibly a Provider:

Each endpoint must document: Required Role(s) – minimum roles that can access the endpoint. Any special rules (e.g., "user must own the booking").

• Unauthenticated requests to protected endpoints return HTTP 401.
• Requests with insufficient permissions return HTTP 403.

• No HTML error pages from API.
• Errors must always return JSON body with standard structure.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields are invalid.",
    "details": {
      "email": ["The email field is required."],
      "trip_id": ["Selected trip is not available for booking."]
    }
  }
}

• code – machine-friendly error code (UPPER_SNAKE).
• message – human-readable message (English, potentially localized later).
• details – optional object with field-level errors.

GET, PUT, DELETE must be idempotent. POST may create new resources on each call; for operations that must not be duplicated (e.g., payment capture), we should support client-provided Idempotency-Key header:

Where capacity-based resources exist (e.g., trip seats): APIs should check remaining capacity at booking time. Fail with 409 CONFLICT and a consistent error code (e.g., TRIP_CAPACITY_REACHED) when sold out.

Primary UI language: Arabic. Secondary: English (for future internationalization).

• All system enums and internal attributes remain in English.
• Arabic labels (as seen in UI, e.g., "ملغاه", "مكتملة") appear only in dedicated fields.

{
  "status": "CANCELLED",
  "status_label_ar": "ملغاه",
  "status_label_en": "Cancelled"
}

Language negotiation: Clients may send Accept-Language: ar. Default: ar if header missing or unsupported.

System currency: SAR (Saudi Riyal).

{
  "currency": "SAR",
  "amount": 24560.0
}

• Default VAT: 15%.
• Any deviations (e.g., 20% shown in Ad Campaigns UI) are documented as discrepancies.

• All APIs must run only under HTTPS.
• Never expose sensitive data (full card numbers, CVV) in logs.
• Avoid placing sensitive information in query strings.
• Payment-related endpoints must follow integration-specific rules.

API should define per-role rate limits:

• End users (B2C mobile/web): generous but bounded rate.
• Admin / Provider: higher limits where needed.
• Machine-to-machine (if introduced later): controlled via API keys.

When a limit is hit: Return 429 Too Many Requests.