REST API Overview

The ZiadaPOS REST API is built with Go + Gin and serves all business logic for the point-of-sale system.

Base URL

http://localhost:8080/api/v1

The base path is configurable via the API_BASE_PATH environment variable.

Standard Response Envelope

All endpoints return JSON wrapped in a standard envelope:

{
  "success": true,
  "message": "Operation completed",
  "data": { ... },
  "errors": null,
  "meta": {
    "total_count": 100,
    "current_page": 1,
    "page_size": 20,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

Authentication

Most endpoints require a JWT Bearer token:

Authorization: Bearer <access_token>

Tokens are obtained via:

• POST /auth/login (password login)
• POST /auth/otp/verify (OTP login)
• POST /auth/register (registration)

Token Lifetimes

Role-Based Access Control

Middleware: RequireOwner() allows admin + owner. RequireAdmin() allows admin only.

Rate Limiting

Redis-backed fixed-window rate limiting is available via RateLimit() middleware. Not applied globally but available for sensitive endpoints.

Pagination

Paginated endpoints accept page and page_size query parameters. Default page_size is 20.

{
  "meta": {
    "total_count": 150,
    "current_page": 2,
    "page_size": 20,
    "total_pages": 8,
    "has_next": true,
    "has_prev": true
  }
}

CORS

Configured via CORS_ALLOWED_ORIGINS (comma-separated). In development, all localhost origins are allowed.

Request ID

Every request receives an X-Request-Id UUID header for tracing, added by the RequestID middleware.

Error Format

{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": {
    "fields": {
      "email": "is required"
    }
  }
}

Modules

The API is organized into 17 domain modules: