🚀 CaterHub GraphQL API

Comprehensive API documentation for all microservices

Welcome to CaterHub API

The CaterHub platform provides a comprehensive GraphQL API that enables seamless integration with our food ordering and management ecosystem. Our microservices architecture ensures scalability, reliability, and maintainability.

Key Features

  • Unified GraphQL Gateway for all services
  • JWT-based authentication with role-based access control
  • Real-time updates via subscriptions
  • Comprehensive audit logging
  • Multi-company support with data isolation
  • RESTful endpoints for legacy integrations

Architecture Overview

Our API follows a microservices architecture with the following components: 

┌─────────────────────────────────────────┐
│         GraphQL Gateway (:8080)         │
└────────────────┬────────────────────────┘
                 │
    ┌────────────┴────────────┬────────────┬────────────┐
    │                         │            │            │
┌───▼───┐  ┌─────▼─────┐  ┌──▼──┐  ┌─────▼────┐  ┌────▼────┐
│  IAM  │  │ BackOffice│  │ CMS │  │ Company  │  │ Finance │
│ :8085 │  │   :8081   │  │:8082│  │  :8083   │  │  :8084  │
└───────┘  └───────────┘  └─────┘  └──────────┘  └─────────┘
    │                         │            │            │
┌───▼───┐  ┌─────▼─────┐  ┌──▼──┐  ┌─────▼────┐
│ Order │  │  Payment  │  │Shop │  │ Database │
│ :8086 │  │   :8087   │  │:8088│  │PostgreSQL│
└───────┘  └───────────┘  └─────┘  └──────────┘

Microservices Documentation

Each service handles specific domain responsibilities within the CaterHub ecosystem.

🔐 IAM Service (Identity & Access)

Handles authentication, authorization, user management, and role-based access control.

Port: :8085
Queries: users, userBy, roles, roleBy
Mutations: loginUser, registerUser, updateUser, deleteUser, createRole, updateRole

🏢 BackOffice Service

Manages administrative operations, settings, vendor configurations, and tier management.

Port: :8081
Queries: settings, tiers, tierCategories, vendorSettings
Mutations: createSetting, updateSetting, createTier, updateTier, createVendorSetting

📝 CMS Service

Content management for pages, posts, media files, topics, trends, FAQs, and newsletters.

Port: :8082
Queries: pages, posts, mediaFiles, topics, trends, faqs, newsletters
Mutations: createPage, updatePost, uploadMedia, createTopic, updateTopic, createTrend, updateTrend, createFAQ, sendNewsletter

🏗️ Company Service

Manages companies, buildings, locations, and organizational structures.

Port: :8083
Queries: companies, companyBy, buildings, countries
Mutations: createCompany, updateCompany, createBuilding, assignCompanyBuilding

💰 Finance Service

Handles financial operations, billing, invoicing, and financial reporting.

Port: :8084
Queries: invoices, transactions, financialReports, balances
Mutations: createInvoice, processPayment, generateReport, reconcileTransactions

📦 Order Service

Manages order lifecycle, cart operations, and order fulfillment.

Port: :8086
Queries: orders, orderBy, carts, orderHistory
Mutations: createOrder, updateOrderStatus, addToCart, checkout

💳 Payment Service

Processes payments, manages payment methods, and handles refunds.

Port: :8087
Queries: paymentMethods, transactions, paymentStatus
Mutations: processPayment, refundPayment, addPaymentMethod, validatePayment

🛍️ Shop Service

Manages products, categories, inventory, and shop configurations.

Port: :8088
Queries: products, categories, inventory, shops
Mutations: createProduct, updateInventory, createCategory, configureShop

Complete API Reference

Comprehensive documentation of all GraphQL queries and mutations available in the CaterHub API.

📊 Queries

Authentication Queries

getMe
Returns: User!
Description: Get the currently authenticated user's information
Authorization: Required

query {
  getMe {
    id
    name
    username
    verified
    roles { roleId role { name capabilities } }
    companyId
  }
}

User Management Queries

users(pagination: PaginationInput)
Returns: Users!
Description: Get paginated list of users
Authorization: Required (admin role)

userBy(getRequest: GetRequestInput!)
Returns: User
Description: Get a single user by filter criteria
Authorization: Required

Example:
query {
  userBy(getRequest: {
    filter: "{\"id\": \"usr_123\"}"
  }) {
    id name username verified roles { roleId }
  }
}

Company Queries

companies(pagination: PaginationInput)
Returns: Companies!
Description: Get paginated list of companies
Authorization: Required

companyBy(getRequest: GetRequestInput!)
Returns: Company
Description: Get a single company by filter criteria
Authorization: Required

countries(pagination: PaginationInput)
Returns: Countries!
Description: Get list of available countries
Authorization: Optional

countryBy(getRequest: GetRequestInput!)
Returns: Country
Description: Get a single country by filter
Authorization: Optional

BackOffice Queries

settings(pagination: PaginationInput)
Returns: Settings!
Description: Get application settings
Authorization: Required

settingBy(getRequest: GetRequestInput!)
Returns: Setting
Description: Get a single setting by filter
Authorization: Required

tiers(pagination: PaginationInput)
Returns: Tiers
Description: Get subscription tiers
Authorization: Optional

tierBy(getRequest: GetRequestInput!)
Returns: Tier
Description: Get a single tier
Authorization: Optional

tierCategories(pagination: PaginationInput)
Returns: TierCategories
Description: Get tier categories
Authorization: Optional

tierCategoryBy(getRequest: GetRequestInput!)
Returns: TierCategory
Description: Get a single tier category
Authorization: Optional

vendorSettings(pagination: PaginationInput)
Returns: VendorSettings!
Description: Get vendor-specific settings
Authorization: Required

vendorSettingBy(getRequest: GetRequestInput!)
Returns: VendorSetting
Description: Get a single vendor setting
Authorization: Required

CMS Queries

pages(pagination: PaginationInput)
Returns: Pages!
Description: Get CMS pages
Authorization: Optional

pageBy(getRequest: GetRequestInput!)
Returns: Page
Description: Get a single page
Authorization: Optional

posts(pagination: PaginationInput)
Returns: Posts!
Description: Get blog posts
Authorization: Optional

postBy(getRequest: GetRequestInput!)
Returns: Post
Description: Get a single post
Authorization: Optional

mediaBy(getRequest: GetRequestInput!)
Returns: MediaFile
Description: Get a single media file with populated relations (uploader, company, regions)
Authorization: Required

getPresignedUploadURLs(input: [PresignedURLInput!]!)
Returns: [PresignedUploadURL!]!
Description: Generate presigned S3 URLs for secure file uploads
Authorization: Required

topics(pagination: PaginationInput)
Returns: Topics
Description: Get discussion topics
Authorization: Optional

topicBy(getRequest: GetRequestInput!)
Returns: Topic
Description: Get a single topic
Authorization: Optional

trends(pagination: PaginationInput)
Returns: Trends!
Description: Get trending topics/items
Authorization: Optional

trendBy(getRequest: GetRequestInput!)
Returns: Trend
Description: Get a single trend
Authorization: Optional

faqs(pagination: PaginationInput)
Returns: Faqs!
Description: Get frequently asked questions
Authorization: Optional

faqBy(getRequest: GetRequestInput!)
Returns: Faq
Description: Get a single FAQ
Authorization: Optional

newsletters(pagination: PaginationInput)
Returns: Newsletters!
Description: Get newsletters
Authorization: Required

newsletterBy(getRequest: GetRequestInput!)
Returns: Newsletter
Description: Get a single newsletter
Authorization: Required

requestForms(pagination: PaginationInput)
Returns: RequestForms!
Description: Get submitted forms
Authorization: Required

requestFormBy(getRequest: GetRequestInput!)
Returns: RequestForm
Description: Get a single form submission
Authorization: Required

Role & Permission Queries

roles(pagination: PaginationInput)
Returns: Roles!
Description: Get available roles
Authorization: Required (admin)

roleBy(getRequest: GetRequestInput!)
Returns: Role
Description: Get a single role
Authorization: Required (admin)

Building & Career Queries

buildings(pagination: PaginationInput)
Returns: Buildings!
Description: Get paginated list of buildings with location data
Authorization: Required

buildingBy(getRequest: GetRequestInput!)
Returns: Building
Description: Get a single building by filter criteria
Authorization: Required

buildingsAutoComplete(keywords: String!, sessionToken: String!, region: String!, limit: Int)
Returns: [Building!]!
Description: Autocomplete search for buildings using Google Places API
Authorization: Required

buildingDetails(placeId: String!, region: String!, buildingId: String, isManagement: Boolean, sessionToken: String!)
Returns: Building!
Description: Fetch building details from Google Places API and create/update in database
Authorization: Required

careers(pagination: PaginationInput)
Returns: Careers!
Description: Get career opportunities
Authorization: Optional

careerBy(getRequest: GetRequestInput!)
Returns: Career
Description: Get a single career posting
Authorization: Optional

✏️ Mutations

Authentication Mutations

loginUser(input: LoginUserInput!)
Returns: LoginUser!
Description: Authenticate user and get tokens
Authorization: None (public)

logoutUser(input: LogoutInput!)
Returns: BooleanResponse!
Description: Logout user and invalidate session
Authorization: Required

renewAccessToken(input: RenewAccessTokenInput!)
Returns: RenewAccessToken!
Description: Refresh authentication token
Authorization: None (requires refresh token)

revokeSession(input: RevokeSessionInput)
Returns: BooleanResponse!
Description: Revoke a user session
Authorization: Required

User Management Mutations

createUser(input: UserInput!)
Returns: User!
Description: Create a new user account
Authorization: Required (admin)

updateUser(id: String!, input: UserInput!)
Returns: User!
Description: Update user information
Authorization: Required (admin or self)

deleteUser(id: String!, roles: [String!]!)
Returns: BooleanResponse!
Description: Delete user account
Authorization: Required (admin)

Company Mutations

createCompany(input: CompanyInput!)
Returns: Company!
Description: Create a new company
Authorization: Required (super admin)

updateCompany(input: CompanyInput!, id: String!)
Returns: Company!
Description: Update company information
Authorization: Required (company admin)

deleteCompany(id: [String!]!)
Returns: BooleanResponse!
Description: Delete companies (soft delete)
Authorization: Required (super admin)

createCountry(input: CountryInput!)
Returns: Country!
Description: Add a new country
Authorization: Required (super admin)

updateCountry(input: CountryInput!, id: String!)
Returns: Country!
Description: Update country information
Authorization: Required (super admin)

deleteCountry(id: [String!]!)
Returns: BooleanResponse!
Description: Delete countries
Authorization: Required (super admin)

Settings Mutations

createSetting(input: SettingInput!)
Returns: Setting!
Description: Create application setting
Authorization: Required (admin)

updateSetting(input: SettingInput!, id: String!)
Returns: Setting!
Description: Update setting value
Authorization: Required (admin)

deleteSetting(id: [String!]!)
Returns: BooleanResponse!
Description: Delete settings
Authorization: Required (admin)

createVendorSetting(input: VendorSettingInput!)
Returns: VendorSetting!
Description: Create vendor-specific setting
Authorization: Required (vendor admin)

updateVendorSetting(input: VendorSettingInput!, id: String!)
Returns: VendorSetting!
Description: Update vendor setting
Authorization: Required (vendor admin)

deleteVendorSetting(id: [String!]!)
Returns: BooleanResponse!
Description: Delete vendor settings
Authorization: Required (vendor admin)

Tier Management Mutations

createTier(input: TierInput!)
Returns: Tier!
Description: Create subscription tier
Authorization: Required (admin)

updateTier(input: TierInput!, id: String!)
Returns: Tier!
Description: Update tier details
Authorization: Required (admin)

deleteTier(id: [String!]!)
Returns: BooleanResponse!
Description: Delete tiers
Authorization: Required (admin)

createTierCategory(input: TierCategoryInput!)
Returns: TierCategory!
Description: Create tier category
Authorization: Required (admin)

updateTierCategory(input: TierCategoryInput!, id: String!)
Returns: TierCategory!
Description: Update tier category
Authorization: Required (admin)

deleteTierCategory(id: [String!]!)
Returns: BooleanResponse!
Description: Delete tier categories
Authorization: Required (admin)

Content Management Mutations

createPage(input: PageInput!)
Returns: Page!
Description: Create CMS page
Authorization: Required (content admin)

updatePage(input: PageInput!, id: String!)
Returns: Page!
Description: Update page content
Authorization: Required (content admin)

deletePage(id: [String!]!)
Returns: BooleanResponse!
Description: Delete pages
Authorization: Required (content admin)

addPageView(id: String!)
Returns: BooleanResponse!
Description: Increment page view counter
Authorization: Optional

createPost(input: PostInput!)
Returns: Post!
Description: Create blog post
Authorization: Required (author)

updatePost(input: PostInput!, id: String!)
Returns: Post!
Description: Update post content
Authorization: Required (author)

deletePost(id: [String!]!)
Returns: BooleanResponse!
Description: Delete posts
Authorization: Required (author)

addPostView(id: String!)
Returns: BooleanResponse!
Description: Increment post view counter
Authorization: Optional

Media Management Mutations

createMediaFile(input: [MediaFileInput!]!)
Returns: [MediaFile!]!
Description: Register uploaded media files in database after S3 upload
Authorization: Required

deleteMediaFile(id: [String!]!)
Returns: BooleanResponse!
Description: Delete media files from database (and optionally S3)
Authorization: Required

FAQ & Newsletter Mutations

createFaq(input: FaqInput!)
Returns: Faq!
Description: Create FAQ entry
Authorization: Required (admin)

updateFaq(input: FaqInput!, id: String!)
Returns: Faq!
Description: Update FAQ
Authorization: Required (admin)

deleteFaq(id: [String!]!)
Returns: BooleanResponse!
Description: Delete FAQs
Authorization: Required (admin)

createNewsletter(input: NewsletterInput!)
Returns: Newsletter!
Description: Create newsletter
Authorization: Required (admin)

updateNewsletter(input: NewsletterInput!, id: String!)
Returns: Newsletter!
Description: Update newsletter
Authorization: Required (admin)

deleteNewsletter(id: [String!]!)
Returns: BooleanResponse!
Description: Delete newsletters
Authorization: Required (admin)

Trend & Topic Mutations

createTrend(input: TrendInput!)
Returns: Trend!
Description: Create trending item
Authorization: Required (admin)

updateTrend(input: TrendInput!, id: String!)
Returns: Trend!
Description: Update trend
Authorization: Required (admin)

deleteTrend(id: [String!]!)
Returns: BooleanResponse!
Description: Delete trends
Authorization: Required (admin)

createTopic(input: TopicInput!)
Returns: Topic!
Description: Create discussion topic
Authorization: Required

updateTopic(input: TopicInput!, id: String!)
Returns: Topic!
Description: Update topic
Authorization: Required (author)

deleteTopic(id: [String!]!)
Returns: BooleanResponse!
Description: Delete topics
Authorization: Required (author/admin)

Form Submissions

createRequestForm(input: RequestFormInput!)
Returns: BooleanResponse!
Description: Submit a general request form
Authorization: Optional

createContactUsRequest(input: RequestFormInput!)
Returns: BooleanResponse!
Description: Submit contact us form
Authorization: Optional

Role Management Mutations

createRole(input: RoleInput!)
Returns: Role!
Description: Create new role
Authorization: Required (super admin)

updateRole(input: RoleInput!, id: String!)
Returns: Role!
Description: Update role permissions
Authorization: Required (super admin)

deleteRole(id: [String!]!)
Returns: BooleanResponse!
Description: Delete roles
Authorization: Required (super admin)

Building Management Mutations

createBuilding(input: BuildingInput!)
Returns: Building!
Description: Add new building manually (alternative to buildingDetails)
Authorization: Required (company admin)

updateBuilding(input: BuildingInput!, id: String!)
Returns: Building!
Description: Update building information and location data
Authorization: Required (company admin)

deleteBuilding(id: [String!]!)
Returns: BooleanResponse!
Description: Soft delete buildings (sets deleted flag)
Authorization: Required (company admin)

Career Management Mutations

createCareer(input: CareerInput!)
Returns: Career!
Description: Post job opening
Authorization: Required (HR admin)

updateCareer(input: CareerInput!, id: String!)
Returns: Career!
Description: Update job posting
Authorization: Required (HR admin)

deleteCareer(id: [String!]!)
Returns: BooleanResponse!
Description: Remove job postings
Authorization: Required (HR admin)

📝 Input Types

Common Input Types

PaginationInput
{
  limit: Int           # Number of items to return (default: 10)
  offset: Int          # Number of items to skip (default: 0)
  filter: String       # JSON string with filter criteria
  sortBy: String       # Field to sort by
  orderBy: String      # Sort order: "asc" or "desc"
  selectedField: String # Fields to return (space-separated)
  populate: String     # Relations to populate
}

GetRequestInput
{
  filter: String!      # JSON string with filter criteria
  selectedField: String # Fields to return (space-separated)
  populate: String     # Relations to populate
}

🔒 Authorization Levels

Access Control

  • None/Public: No authentication required
  • Optional: Works with or without authentication
  • Required: Must be authenticated
  • Required (role): Must have specific role
  • Required (admin): Must have admin role
  • Required (super admin): Must be level 1 user

Authentication & Authorization

JWT Authentication

All API requests (except public endpoints) require a valid JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Obtaining a Token

Use the loginUser mutation to authenticate and receive tokens:

mutation {
  loginUser(input: {
    username: "user@example.com"
    password: "securePassword123"
  }) {
    user {
      id
      name
      roles {
        roleId
        role {
          name
          capabilities
        }
      }
    }
    token
    refreshToken
  }
}

Authorization Levels

  • Level 1 (Super Admin): Full access to all APIs, bypasses OPA policies
  • Level 2+ (Regular Users): Access controlled by OPA policies and role capabilities
  • Public Access: Limited endpoints available without authentication

Company Context

For multi-company operations, include the company ID header:

x-company-id: YOUR_COMPANY_ID

Public Endpoints

The following endpoints are accessible without authentication:

  • /api.AuthService/LoginUser
  • /api.AuthService/RegisterUser
  • /api.AuthService/ForgotPassword
  • /api.AuthService/ResetPassword
  • /api.AuthService/RefreshToken

Token Refresh

Use the refresh token to obtain a new access token:

mutation {
  refreshToken(input: {
    refreshToken: "YOUR_REFRESH_TOKEN"
  }) {
    token
    refreshToken
  }
}

Complete API Examples with Request & Response

Full examples showing requests, successful responses, and error scenarios for each service.

🔐 IAM Service Examples

Login User

REQUEST:
mutation {
  loginUser(input: {
    username: "john.doe@example.com"
    password: "SecurePassword123!"
  }) {
    user {
      id
      name
      username
      verified
      roles {
        roleId
        role {
          name
          capabilities
        }
      }
    }
    token
    refreshToken
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "loginUser": {
      "user": {
        "id": "usr_7f3a4b5c6d7e8f9a",
        "name": "John Doe",
        "username": "john.doe@example.com",
        "verified": true,
        "roles": [
          {
            "roleId": "rol_admin_001",
            "role": {
              "name": "Administrator",
              "capabilities": ["read", "write", "delete", "admin"]
            }
          }
        ]
      },
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

ERROR RESPONSE (Invalid Credentials):
{
  "errors": [
    {
      "message": "Invalid username or password",
      "extensions": {
        "code": "UNAUTHENTICATED",
        "field": "password"
      }
    }
  ]
}

Create User

REQUEST:
mutation {
  createUser(input: {
    name: "Jane Smith"
    username: "jane.smith@example.com"
    password: "SecurePass456!"
    companyId: "cmp_123abc456def"
    roleIds: ["rol_user_001"]
  }) {
    id
    name
    username
    createdAt
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "createUser": {
      "id": "usr_9b8c7d6e5f4a3b2c",
      "name": "Jane Smith",
      "username": "jane.smith@example.com",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

ERROR RESPONSE (User Already Exists):
{
  "errors": [
    {
      "message": "User with this email already exists",
      "extensions": {
        "code": "ALREADY_EXISTS",
        "field": "username"
      }
    }
  ]
}

🏢 BackOffice Service Examples

Get Settings with Pagination

REQUEST:
query {
  settings(pagination: {
    limit: 5,
    offset: 0,
    filter: "{\"status\": \"active\", \"countryId\": \"ctr_us_001\"}",
    sortBy: "key",
    orderBy: "asc"
  }) {
    total
    settings {
      id
      key
      value
      status
      countryId
      createdAt
      updatedAt
    }
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "settings": {
      "total": 23,
      "settings": [
        {
          "id": "set_001",
          "key": "app.maintenance.mode",
          "value": "false",
          "status": "active",
          "countryId": "ctr_us_001",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-15T14:30:00Z"
        },
        {
          "id": "set_002",
          "key": "app.max.order.value",
          "value": "5000",
          "status": "active",
          "countryId": "ctr_us_001",
          "createdAt": "2024-01-02T00:00:00Z",
          "updatedAt": "2024-01-10T09:15:00Z"
        }
      ]
    }
  }
}

ERROR RESPONSE (Invalid Filter):
{
  "errors": [
    {
      "message": "Invalid filter format",
      "extensions": {
        "code": "BAD_USER_INPUT",
        "field": "filter"
      }
    }
  ]
}

Create Tier

REQUEST:
mutation {
  createTier(input: {
    name: "Premium",
    level: 2,
    description: "Premium tier with advanced features",
    benefits: ["Priority support", "Advanced analytics", "Custom branding"],
    price: 99.99,
    status: "active"
  }) {
    id
    name
    level
    description
    benefits
    price
    status
    createdAt
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "createTier": {
      "id": "tier_prem_001",
      "name": "Premium",
      "level": 2,
      "description": "Premium tier with advanced features",
      "benefits": ["Priority support", "Advanced analytics", "Custom branding"],
      "price": 99.99,
      "status": "active",
      "createdAt": "2024-01-15T15:45:00Z"
    }
  }
}

ERROR RESPONSE (Duplicate Tier Level):
{
  "errors": [
    {
      "message": "A tier with level 2 already exists",
      "extensions": {
        "code": "CONFLICT",
        "field": "level"
      }
    }
  ]
}

🏗️ Company Service Examples

Get Company with Buildings

REQUEST:
query {
  companyBy(getRequest: {
    filter: "{\"id\": \"cmp_123abc456def\"}",
    selectedField: "id name status buildings countries"
  }) {
    id
    name
    status
    buildings {
      id
      name
      address
      floors
      capacity
    }
    countries {
      id
      name
      code
    }
    createdAt
    updatedAt
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "companyBy": {
      "id": "cmp_123abc456def",
      "name": "Acme Corporation",
      "status": "active",
      "buildings": [
        {
          "id": "bld_001",
          "name": "Headquarters",
          "address": "100 Main St, New York, NY 10001",
          "floors": 25,
          "capacity": 1500
        },
        {
          "id": "bld_002",
          "name": "Tech Campus",
          "address": "500 Tech Blvd, San Francisco, CA 94105",
          "floors": 10,
          "capacity": 800
        }
      ],
      "countries": [
        {
          "id": "ctr_us_001",
          "name": "United States",
          "code": "US"
        }
      ],
      "createdAt": "2023-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T12:00:00Z"
    }
  }
}

ERROR RESPONSE (Company Not Found):
{
  "errors": [
    {
      "message": "Company not found",
      "extensions": {
        "code": "NOT_FOUND",
        "field": "id"
      }
    }
  ]
}

Update Company

REQUEST:
mutation {
  updateCompany(
    id: "cmp_123abc456def",
    input: {
      name: "Acme Global Corporation",
      status: "active",
      description: "Leading technology solutions provider",
      website: "https://acme.com",
      contactEmail: "info@acme.com"
    }
  ) {
    id
    name
    status
    description
    website
    contactEmail
    updatedAt
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "updateCompany": {
      "id": "cmp_123abc456def",
      "name": "Acme Global Corporation",
      "status": "active",
      "description": "Leading technology solutions provider",
      "website": "https://acme.com",
      "contactEmail": "info@acme.com",
      "updatedAt": "2024-01-15T16:30:00Z"
    }
  }
}

ERROR RESPONSE (Unauthorized):
{
  "errors": [
    {
      "message": "You don't have permission to update this company",
      "extensions": {
        "code": "FORBIDDEN",
        "field": "authorization"
      }
    }
  ]
}

📝 CMS Service Examples

Get Media By Filter

REQUEST:
query GetMedia($getRequest: GetRequestInput!) {
  mediaBy(getRequest: $getRequest) {
    id
    filename
    mimeType
    url
    uploader { id name }
    company { id name }
    regions { id name }
    companyId
    countryIds
    createdBy
  }
}

Variables:
{
  "getRequest": {
    "filter": "{\"id\": \"c111b697-abf7-4abf-94e9-93519438ac68\"}",
    "selectedField": "id filename mime_type url created_at uploader company regions",
    "populate": "[{\"path\": \"uploader\"}, {\"path\":\"company\"}, {\"path\": \"regions\"}]"
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "mediaBy": {
      "id": "c111b697-abf7-4abf-94e9-93519438ac68",
      "filename": "adaptive-icon.png",
      "mimeType": "image/png",
      "url": "https://development.caterhub.io.s3.amazonaws.com/corporate/...",
      "uploader": { "id": "c1942ad3-ff96-4b7e-98bd-2d01bbdd12ad", "name": "Muhammad Zakir" },
      "company": { "id": "9372e081-0ed1-472a-8f55-e7d7785fefbf", "name": "CaterHub" },
      "regions": null,
      "companyId": "9372e081-0ed1-472a-8f55-e7d7785fefbf",
      "countryIds": null,
      "createdBy": "c1942ad3-ff96-4b7e-98bd-2d01bbdd12ad"
    }
  }
}

Get Presigned Upload URLs

REQUEST:
mutation GetPresignedURL($input: [PresignedURLInput!]!) {
  getPresignedUploadURLs(input: $input) {
    url
    key
    bucket
    filename
  }
}

Variables:
{
  "input": [{
    "filename": "document.pdf",
    "mimeType": "application/pdf",
    "isPrivate": false,
    "uploadOn": "corporate"
  }]
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "getPresignedUploadURLs": [{
      "url": "https://development.caterhub.io.s3.amazonaws.com/corporate/...",
      "key": "corporate/9372e081-0ed1-472a-8f55-e7d7785fefbf/uuid-document.pdf",
      "bucket": "development.caterhub.io",
      "filename": "document.pdf"
    }]
  }
}

WORKFLOW:
1. Call getPresignedUploadURLs to get S3 upload URL
2. Upload file to S3 using the presigned URL (HTTP PUT)
3. Call createMediaFile to register the uploaded file in database

Create Page

REQUEST:
mutation {
  createPage(input: {
    title: "About Us",
    slug: "about-us",
    content: "
About Our Company
We are a leading...
",
    metaTitle: "About Acme Corporation",
    metaDescription: "Learn about Acme Corporation's history and mission",
    status: "published",
    author: "usr_7f3a4b5c6d7e8f9a"
  }) {
    id
    title
    slug
    status
    publishedAt
    author {
      name
    }
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "createPage": {
      "id": "page_about_001",
      "title": "About Us",
      "slug": "about-us",
      "status": "published",
      "publishedAt": "2024-01-15T17:00:00Z",
      "author": {
        "name": "John Doe"
      }
    }
  }
}

ERROR RESPONSE (Duplicate Slug):
{
  "errors": [
    {
      "message": "A page with slug 'about-us' already exists",
      "extensions": {
        "code": "ALREADY_EXISTS",
        "field": "slug"
      }
    }
  ]
}

📦 Order Service Examples

Create Order

REQUEST:
mutation {
  createOrder(input: {
    customerId: "usr_customer_001",
    restaurantId: "rest_001",
    items: [
      {
        productId: "prod_burger_001",
        quantity: 2,
        price: 12.99,
        notes: "No pickles"
      },
      {
        productId: "prod_fries_001",
        quantity: 1,
        price: 4.99
      }
    ],
    deliveryType: "delivery",
    deliveryAddress: {
      street: "123 Main St",
      city: "New York",
      state: "NY",
      zipCode: "10001"
    },
    paymentMethodId: "pm_card_001",
    scheduledFor: "2024-01-15T19:00:00Z"
  }) {
    id
    orderNumber
    status
    totalAmount
    tax
    deliveryFee
    grandTotal
    items {
      productId
      productName
      quantity
      price
      subtotal
    }
    estimatedDeliveryTime
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "createOrder": {
      "id": "ord_20240115_001",
      "orderNumber": "ORD-2024-0001",
      "status": "pending",
      "totalAmount": 30.97,
      "tax": 2.79,
      "deliveryFee": 5.00,
      "grandTotal": 38.76,
      "items": [
        {
          "productId": "prod_burger_001",
          "productName": "Classic Burger",
          "quantity": 2,
          "price": 12.99,
          "subtotal": 25.98
        },
        {
          "productId": "prod_fries_001",
          "productName": "French Fries",
          "quantity": 1,
          "price": 4.99,
          "subtotal": 4.99
        }
      ],
      "estimatedDeliveryTime": "2024-01-15T19:30:00Z"
    }
  }
}

ERROR RESPONSE (Restaurant Closed):
{
  "errors": [
    {
      "message": "Restaurant is currently closed",
      "extensions": {
        "code": "UNAVAILABLE",
        "field": "restaurantId",
        "details": {
          "opensAt": "2024-01-16T11:00:00Z"
        }
      }
    }
  ]
}

Update Order Status

REQUEST:
mutation {
  updateOrderStatus(
    orderId: "ord_20240115_001",
    status: "preparing",
    notes: "Order confirmed and being prepared"
  ) {
    id
    status
    statusHistory {
      status
      timestamp
      notes
      updatedBy
    }
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "updateOrderStatus": {
      "id": "ord_20240115_001",
      "status": "preparing",
      "statusHistory": [
        {
          "status": "pending",
          "timestamp": "2024-01-15T18:00:00Z",
          "notes": "Order placed",
          "updatedBy": "System"
        },
        {
          "status": "confirmed",
          "timestamp": "2024-01-15T18:02:00Z",
          "notes": "Order confirmed by restaurant",
          "updatedBy": "rest_001"
        },
        {
          "status": "preparing",
          "timestamp": "2024-01-15T18:05:00Z",
          "notes": "Order confirmed and being prepared",
          "updatedBy": "usr_staff_001"
        }
      ]
    }
  }
}

ERROR RESPONSE (Invalid Status Transition):
{
  "errors": [
    {
      "message": "Cannot transition from 'delivered' to 'preparing'",
      "extensions": {
        "code": "INVALID_STATE",
        "field": "status",
        "currentStatus": "delivered",
        "requestedStatus": "preparing"
      }
    }
  ]
}

💳 Payment Service Examples

Process Payment

REQUEST:
mutation {
  processPayment(input: {
    orderId: "ord_20240115_001",
    amount: 38.76,
    currency: "USD",
    paymentMethodId: "pm_card_001",
    savePaymentMethod: true
  }) {
    id
    transactionId
    status
    amount
    currency
    paymentMethod {
      type
      last4
      brand
    }
    processedAt
    receipt
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "processPayment": {
      "id": "pay_tx_001",
      "transactionId": "tx_stripe_4b3c2d1e",
      "status": "succeeded",
      "amount": 38.76,
      "currency": "USD",
      "paymentMethod": {
        "type": "card",
        "last4": "4242",
        "brand": "Visa"
      },
      "processedAt": "2024-01-15T18:10:00Z",
      "receipt": "https://payments.caterhub.io/receipts/pay_tx_001"
    }
  }
}

ERROR RESPONSE (Card Declined):
{
  "errors": [
    {
      "message": "Payment failed: Card was declined",
      "extensions": {
        "code": "PAYMENT_FAILED",
        "declineCode": "insufficient_funds",
        "paymentMethodId": "pm_card_001"
      }
    }
  ]
}

🛍️ Shop Service Examples

Get Products with Filters

REQUEST:
query {
  products(pagination: {
    limit: 10,
    offset: 0,
    filter: "{\"category\": \"burgers\", \"available\": true, \"priceRange\": {\"min\": 5, \"max\": 20}}",
    sortBy: "popularity",
    orderBy: "desc"
  }) {
    total
    products {
      id
      name
      description
      price
      currency
      category {
        id
        name
      }
      images
      nutritionInfo {
        calories
        protein
        carbs
        fat
      }
      allergens
      available
      preparationTime
    }
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "products": {
      "total": 15,
      "products": [
        {
          "id": "prod_burger_001",
          "name": "Classic Burger",
          "description": "Juicy beef patty with lettuce, tomato, and our special sauce",
          "price": 12.99,
          "currency": "USD",
          "category": {
            "id": "cat_burgers",
            "name": "Burgers"
          },
          "images": [
            "https://cdn.caterhub.io/products/classic-burger.jpg"
          ],
          "nutritionInfo": {
            "calories": 550,
            "protein": 25,
            "carbs": 45,
            "fat": 30
          },
          "allergens": ["gluten", "dairy"],
          "available": true,
          "preparationTime": 15
        }
      ]
    }
  }
}

ERROR RESPONSE (Invalid Category):
{
  "errors": [
    {
      "message": "Category 'invalid_category' does not exist",
      "extensions": {
        "code": "NOT_FOUND",
        "field": "category",
        "availableCategories": ["burgers", "pizzas", "salads", "drinks", "desserts"]
      }
    }
  ]
}

💰 Finance Service Examples

Generate Financial Report

REQUEST:
mutation {
  generateFinancialReport(input: {
    companyId: "cmp_123abc456def",
    reportType: "monthly_revenue",
    startDate: "2024-01-01",
    endDate: "2024-01-31",
    groupBy: "day",
    includeDetails: true
  }) {
    id
    reportType
    period {
      start
      end
    }
    summary {
      totalRevenue
      totalOrders
      averageOrderValue
      topSellingProducts
    }
    dailyBreakdown {
      date
      revenue
      orderCount
      averageOrderValue
    }
    generatedAt
    downloadUrl
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "generateFinancialReport": {
      "id": "report_fin_202401",
      "reportType": "monthly_revenue",
      "period": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-31T23:59:59Z"
      },
      "summary": {
        "totalRevenue": 125430.50,
        "totalOrders": 3421,
        "averageOrderValue": 36.67,
        "topSellingProducts": [
          "Classic Burger",
          "Margherita Pizza",
          "Caesar Salad"
        ]
      },
      "dailyBreakdown": [
        {
          "date": "2024-01-01",
          "revenue": 3250.75,
          "orderCount": 89,
          "averageOrderValue": 36.52
        },
        {
          "date": "2024-01-02",
          "revenue": 4120.30,
          "orderCount": 112,
          "averageOrderValue": 36.79
        }
      ],
      "generatedAt": "2024-02-01T10:00:00Z",
      "downloadUrl": "https://reports.caterhub.io/download/report_fin_202401"
    }
  }
}

ERROR RESPONSE (Insufficient Permissions):
{
  "errors": [
    {
      "message": "You don't have permission to generate financial reports",
      "extensions": {
        "code": "FORBIDDEN",
        "requiredRole": "finance_admin",
        "currentRole": "viewer"
      }
    }
  ]
}

🏗️ Building Management Examples

Buildings AutoComplete

REQUEST:
query BuildingsAutoComplete(
  $keywords: String!
  $sessionToken: String!
  $region: String!
  $limit: Int
) {
  buildingsAutoComplete(
    keywords: $keywords
    sessionToken: $sessionToken
    region: $region
    limit: $limit
  ) {
    id
    name
    address
    placeId
    city
    region
    latitude
    longitude
  }
}

Variables:
{
  "keywords": "Equ",
  "sessionToken": "9372e081-0ed1-472a-8f55-e7d7785fefbf",
  "region": "MY",
  "limit": 10
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "buildingsAutoComplete": [
      {
        "id": "3f873ec8-355b-472f-b563-f6a50d421efa",
        "name": "Equatorial Plaza",
        "address": "Lot 1217, Jln Sultan Ismail, Kuala Lumpur, Malaysia",
        "placeId": "ChIJpyDjtUQ3zDERbwHDrvblWJc",
        "city": "Kuala Lumpur",
        "region": "MY",
        "latitude": 3.153015,
        "longitude": 101.709298
      }
    ]
  }
}

Get Building Details (from Google Places)

REQUEST:
query GetBuildingDetails(
  $placeId: String!
  $region: String!
  $sessionToken: String!
) {
  buildingDetails(
    placeId: $placeId
    region: $region
    sessionToken: $sessionToken
    isManagement: false
  ) {
    id
    name
    address
    city
    postalCode
    latitude
    longitude
    placeId
  }
}

Variables:
{
  "placeId": "ChIJB4x1rNZQ0DERFtqFdw5NFaQ",
  "region": "my",
  "sessionToken": "9372e081-0ed1-472a-8f55-23wdasr"
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "buildingDetails": {
      "id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "name": "Menara Kuala Lumpur",
      "address": "Jalan P Ramlee, Kuala Lumpur, 50250, Malaysia",
      "city": "Kuala Lumpur",
      "postalCode": "50250",
      "latitude": 3.1524,
      "longitude": 101.7032,
      "placeId": "ChIJB4x1rNZQ0DERFtqFdw5NFaQ"
    }
  }
}

WORKFLOW:
1. User searches via buildingsAutoComplete with keywords
2. User selects a building from autocomplete results
3. Call buildingDetails with placeId to fetch/save complete details
4. Building is created in database if it doesn't exist

Update Building

REQUEST:
mutation UpdateBuilding($id: String!, $input: BuildingInput!) {
  updateBuilding(id: $id, input: $input) {
    id
    name
    address
    city
    isManagement
    updatedAt
  }
}

Variables:
{
  "id": "0606dcfa-1d81-4d03-a2fc-c984a1d3e867",
  "input": {
    "name": "Square One Shopping Centre",
    "address": "Jalan Flora Utama, 83000 Batu Pahat, Johor, Malaysia",
    "city": "Batu Pahat",
    "isManagement": true
  }
}

SUCCESSFUL RESPONSE:
{
  "data": {
    "updateBuilding": {
      "id": "0606dcfa-1d81-4d03-a2fc-c984a1d3e867",
      "name": "Square One Shopping Centre",
      "address": "Jalan Flora Utama, 83000 Batu Pahat, Johor, Malaysia",
      "city": "Batu Pahat",
      "isManagement": true,
      "updatedAt": "2025-10-01T15:20:45.123456Z"
    }
  }
}

Common Error Response Patterns

1. VALIDATION ERROR:
{
  "errors": [
    {
      "message": "Validation failed",
      "extensions": {
        "code": "BAD_USER_INPUT",
        "validationErrors": [
          {
            "field": "email",
            "message": "Invalid email format"
          },
          {
            "field": "password",
            "message": "Password must be at least 8 characters"
          }
        ]
      }
    }
  ]
}

2. AUTHENTICATION ERROR:
{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED",
        "authenticateUrl": "/auth/login"
      }
    }
  ]
}

3. RATE LIMITING ERROR:
{
  "errors": [
    {
      "message": "Rate limit exceeded",
      "extensions": {
        "code": "TOO_MANY_REQUESTS",
        "retryAfter": 3600,
        "limit": 1000,
        "remaining": 0,
        "resetAt": "2024-01-15T19:00:00Z"
      }
    }
  ]
}

4. SERVER ERROR:
{
  "errors": [
    {
      "message": "Internal server error",
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR",
        "traceId": "trace_abc123def456",
        "timestamp": "2024-01-15T18:30:00Z"
      }
    }
  ]
}

📚 Documentation Mapping Guide

This guide maps the comprehensive GRAPHQL_API_DOCUMENTATION.md to this live /docs endpoint.

Documentation Sources

🌐 /docs Endpoint (This Page)

Access: http://localhost:8080/docs

Interactive HTML documentation with tabbed navigation, live examples, and service organization.

  • Quick reference and testing
  • Interactive examples
  • Tabbed navigation by topic
  • Live in browser

📄 GRAPHQL_API_DOCUMENTATION.md

Location: Repository root

Comprehensive markdown documentation with detailed tables, curl commands, and complete field specifications.

  • Complete field documentation
  • All curl command examples
  • Searchable markdown format
  • Best for integration guides

Service Organization

Both documentation sources organize APIs by microservices:

IAM Service (Port :8085)
┌─ Authentication
│  ├─ loginUser → /docs: "Authentication Mutations" | GRAPHQL_API_DOCUMENTATION.md: "Authentication → Login User"
│  └─ getMe → /docs: "Authentication Queries" | GRAPHQL_API_DOCUMENTATION.md: "Authentication → Get Current User"
├─ User Management
│  ├─ users, userBy → /docs: "User Management Queries"
│  └─ createUser, updateUser, deleteUser → /docs: "User Management Mutations"
└─ Role Management
   ├─ roles, roleBy → /docs: "Role & Permission Queries"
   └─ createRole, updateRole, deleteRole → /docs: "Role Management Mutations"

BackOffice Service (Port :8081)
┌─ Settings Management
│  ├─ settings, settingBy → /docs: "BackOffice Queries"
│  └─ createSetting, updateSetting, deleteSetting → /docs: "Settings Mutations"
├─ Tier Management
│  ├─ tiers, tierBy → /docs: "BackOffice Queries"
│  └─ createTier, updateTier, deleteTier → /docs: "Tier Management Mutations"
└─ Vendor Settings
   ├─ vendorSettings, vendorSettingBy → /docs: "BackOffice Queries"
   └─ createVendorSetting, updateVendorSetting → /docs: "Settings Mutations"

CMS Service (Port :8082)
┌─ Content Management
│  ├─ pages, posts → /docs: "CMS Queries"
│  └─ createPage, updatePost → /docs: "Content Management Mutations"
├─ Media Management ✨
│  ├─ mediaBy → /docs: "CMS Queries" | GRAPHQL_API_DOCUMENTATION.md: "Media Management → Get Media By Filter"
│  ├─ getPresignedUploadURLs → /docs: "CMS Queries" | GRAPHQL_API_DOCUMENTATION.md: "Media Management → Get Presigned URLs"
│  └─ createMediaFile, deleteMediaFile → /docs: "Media Management Mutations"
└─ Topics & Trends
   ├─ topics, trends → /docs: "CMS Queries"
   └─ createTopic, createTrend → /docs: "Trend & Topic Mutations"

Company/Building Service (Port :8083)
┌─ Company Management
│  ├─ companies, companyBy → /docs: "Company Queries"
│  └─ createCompany, updateCompany, deleteCompany → /docs: "Company Mutations"
├─ Country Management
│  ├─ countries, countryBy → /docs: "Company Queries"
│  └─ createCountry, updateCountry, deleteCountry → /docs: "Company Mutations"
└─ Building Management ✨
   ├─ buildings, buildingBy → /docs: "Building & Career Queries"
   ├─ buildingsAutoComplete → /docs: "Building & Career Queries" | GRAPHQL_API_DOCUMENTATION.md: "Building Management → AutoComplete"
   ├─ buildingDetails → /docs: "Building & Career Queries" | GRAPHQL_API_DOCUMENTATION.md: "Building Management → Get Details"
   └─ updateBuilding, deleteBuilding → /docs: "Building Management Mutations"

Finding Documentation

For Quick Testing

  1. Go to API Reference tab
  2. Find your query/mutation by service
  3. Check Examples tab for request format
  4. Test in GraphQL Playground

For Detailed Integration

  1. Open GRAPHQL_API_DOCUMENTATION.md
  2. Use Table of Contents to navigate
  3. Review complete field specifications
  4. Copy curl command examples
  5. Review notes for important details

Recently Added Features ✨

Media Management (CMS Service)
• mediaBy - Query single media with populated relations (uploader, company, regions)
• getPresignedUploadURLs - Generate S3 upload URLs for secure file uploads
• createMediaFile - Register media in database after S3 upload
• deleteMediaFile - Remove media files

Building Management (Company Service)
• buildings - List buildings with pagination and filters
• buildingBy - Query single building by filter
• buildingsAutoComplete - Google Places API autocomplete search
• buildingDetails - Fetch from Google Places and create/update in database
• updateBuilding - Update building information
• deleteBuilding - Soft delete buildings

Authentication
• getMe - Get current authenticated user with roles and capabilities

Documentation Comparison

Feature /docs Endpoint GRAPHQL_API_DOCUMENTATION.md
Format Interactive HTML Markdown
Access Web browser at localhost:8080/docs File in repository
Examples Selected key examples Comprehensive examples for all endpoints
Field Docs Brief descriptions Complete field specification tables
curl Commands Some examples All examples include curl
Navigation Tabbed interface Searchable markdown with TOC
Best For Quick reference, testing Development, integration guides

Additional Resources

📋 Schema JSON

Complete schema definition in JSON format

🗺️ Schema Voyager

Interactive graph visualization of schema relationships

🎮 GraphQL Playground

Interactive testing environment (local/staging only)

Development Tools

📋 Schema Documentation

Complete JSON schema reference with all types, queries, mutations, and subscriptions available in the API.

🗺️ Schema Voyager

Interactive graph visualization of the GraphQL schema relationships. Explore how types connect to each other.

👋 REST Health Check

Simple REST endpoint for testing connectivity and service health status.

📚 Complete API Documentation

For comprehensive documentation with detailed examples, request/response formats, and complete field descriptions, refer to: 

GRAPHQL_API_DOCUMENTATION.md

This document contains detailed documentation for all queries and mutations organized by domain:

Authentication & IAM Service:
• Login User - JWT authentication with token generation
• Get Current User (getMe) - Retrieve authenticated user profile with roles

User & Role Management:
• Users CRUD operations with pagination
• Role-based access control (RBAC) configuration

Company & Country Management:
• Multi-company support with data isolation
• Country configuration and management

Settings Management:
• Application settings grouped by company
• Vendor-specific settings configuration

Tier Management:
• Subscription tier categories and tiers
• Tiered pricing and benefits configuration

CMS Service:
• Page and Post management
• Media Management:
  - Get Media By Filter (mediaBy) with population
  - Get Presigned Upload URLs for S3
  - Create Media File after S3 upload
  - Delete Media files
• Topics, Trends, FAQs, Newsletters
• Request forms and contact submissions

Building Management:
• Get Buildings with pagination and filters
• Buildings AutoComplete - Google Places API integration
• Building Details - Fetch from Google Places and create/update
• Update and Delete buildings with soft delete support

Each section includes:
✓ Complete query/mutation syntax
✓ Variable examples with actual data
✓ Input field specifications
✓ Response field documentation
✓ Example requests (curl commands)
✓ Example responses (JSON)
✓ Detailed usage notes and workflows

Useful Resources

  • GraphQL Best Practices Guide
  • API Rate Limiting: 1000 requests/hour per token
  • Webhook Support for real-time events
  • SDK available for JavaScript, Python, Go
  • Postman Collection available for import
  • Complete Documentation: GRAPHQL_API_DOCUMENTATION.md

Error Handling

The API returns standardized error responses:

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED",
        "field": "authorization"
      }
    }
  ]
}

Contact & Support

For API support, bug reports, or feature requests:
📧 Email: api-support@caterhub.io
📚 Documentation: https://docs.caterhub.io
🐛 Issues: https://github.com/CaterHub/api/issues

GraphQL Playground is not available in production. Use the API Reference documentation above.