API Endpoints

Overview

Q01 Core APIs expose a RESTful interface through CoreService API Gateway. All endpoints follow consistent patterns for authentication, filtering, pagination, and error handling.

Base URL: https://api.example.com

API Version: /api/v4

Authentication: All endpoints require JWT token in Authorization header

Authentication

Required Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Endpoints

POST /auth/login
Content-Type: application/json

{
  "username": "user@example.com",
  "password": "secure_password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Refresh Token

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Custom Headers

Beyond the required Authorization header, the platform supports special custom headers for advanced routing, deployment strategies, and developer workflows.

canary-mode

Purpose: Route requests to canary deployment instances for gradual rollout testing.

Header:

canary-mode: on

Use Case:

Test new platform versions with production traffic
Gradual rollout strategy (e.g., 10% of requests to canary)
A/B testing of API changes

Example:

GET /api/v4/core/PRD
Authorization: Bearer {token}
canary-mode: on

Behavior:

Request routed to canary deployment instances
Useful for testing new features before full deployment
Monitor canary metrics vs stable deployment

developer

Purpose: Route requests to a specific developer's Skaffold instance for local development/debugging.

Header:

developer: {developer_name}

Use Case:

Local development with production data
Debugging specific issues in dev environment
Testing changes before deployment

Example:

GET /api/v4/core/PRD
Authorization: Bearer {token}
developer: peter

Behavior:

Request routed to Peter's Skaffold instance (e.g., localhost:8080)
Developer can debug/test changes with production API calls
Isolated from other developers and production

microservice

Purpose: Explicitly specify which microservice should handle the request.

Header:

microservice: {microservice_name}

Use Case:

Override default routing logic
Direct requests to specific microservice instances
Testing microservice-specific behavior

Example:

GET /api/v4/core/ART
Authorization: Bearer {token}
microservice: mssettings

Behavior:

CoreService routes request to specified microservice
Useful when dimension is accessible from multiple microservices
Bypasses automatic microservice resolution

Combining Custom Headers

Example: Canary + Developer:

GET /api/v4/core/PRD
Authorization: Bearer {token}
canary-mode: on
developer: peter

Example: Microservice + Developer:

GET /api/v4/core/ART
Authorization: Bearer {token}
microservice: mssettings
developer: alice

Custom Headers Summary

Header	Value	Purpose
canary-mode	`on`	Route to canary deployment
developer	`{name}`	Route to developer's Skaffold instance
microservice	`{name}`	Specify microservice for routing

⚠️ Production Usage:

canary-mode: Used in production for gradual rollouts
developer: Development/testing only (NOT for production)
microservice: Rarely needed (platform auto-routes correctly)

CRUD Operations

List Records (Collection)

GET /api/v4/core/{dim}
Authorization: Bearer {token}

Path Parameters:

{dim} - Dimension code (e.g., PRD, ORD, CUST)

Query Parameters:

Parameter	Type	Description	Example
`$num_rows`	integer	Number of records to return	`?$num_rows=100`
`$offset`	integer	Number of records to skip	`?$offset=0`
`$fields`	string	Comma-separated fields to return	`?$fields=XPRD01,XPRD02`
`$expand`	string	Related dimensions to include	`?$expand=category,supplier`
`filter[field]`	mixed	Filter by field value	`?filter[XPRD05]=electronics`
`filter[field][$operator]`	mixed	Filter with operator	`?filter[XPRD02][$gt]=100`
`sort`	string	Sort fields (prefix with `-` for DESC)	`?sort=-CREATED_AT`

Filter Operators:

$eq - Equals (default)
$ne - Not equals
$gt - Greater than
$gte - Greater than or equal
$lt - Less than
$lte - Less than or equal
$in - In list
$nin - Not in list
$like - Pattern match (SQL LIKE)
$between - Between two values

Example:

GET /api/v4/core/PRD?$num_rows=10&$offset=0&filter[XPRD05]=electronics&sort=-CREATED_AT

Response:

{
  "data": [
    {
      "PRD_ID": 123,
      "XPRD01": "Widget Pro",
      "XPRD02": 99.99,
      "XPRD05": "electronics",
      "CREATED_AT": "20251219153045"
    }
  ],
  "meta": {
    "total": 156,
    "num_rows": 10,
    "offset": 0,
    "has_more": true
  }
}

Get Single Record

GET /api/v4/core/{dim}/{id}
Authorization: Bearer {token}

Path Parameters:

{dim} - Dimension code
{id} - Record ID

Query Parameters:

$fields - Select specific fields
$expand - Include related dimensions

Example:

GET /api/v4/core/PRD/123?$expand=category

Response:

{
  "data": {
    "PRD_ID": 123,
    "XPRD01": "Widget Pro",
    "XPRD02": 99.99,
    "XPRD05": "cat_123",
    "category": {
      "CAT_ID": "cat_123",
      "XCAT01": "Electronics",
      "XCAT02": "Electronic devices and accessories"
    },
    "CREATED_AT": "20251219153045"
  }
}

Create Record

POST /api/v4/core/{dim}
Authorization: Bearer {token}
Content-Type: application/json

{
  "data": {
    "XPRD01": "New Product",
    "XPRD02": 99.99,
    "XPRD05": "cat_123"
  }
}

Path Parameters:

{dim} - Dimension code

Request Body:

data (object) - Field values (only fields with COD_ON_OFF containing 'N')

Response:

{
  "data": {
    "PRD_ID": 124,
    "TREC": "N",
    "CDATA": "20251219160000",
    "OWNER": "user@example.com",
    "XPRD01": "New Product",
    "XPRD02": 99.99,
    "XPRD05": "cat_123"
  },
  "message": "Record created successfully",
  "event_id": "uuid-..."
}

Full Update

PUT /api/v4/core/{dim}/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "data": {
    "XPRD01": "Updated Product",
    "XPRD02": 109.99,
    "XPRD05": "cat_123",
    "XPRD06": true
  }
}

Path Parameters:

{dim} - Dimension code
{id} - Record ID

Request Body:

data (object) - All modifiable fields (COD_ON_OFF containing 'M')

Response:

{
  "data": {
    "PRD_ID": 123,
    "TREC": "M",
    "LDATA": "20251219170000",
    "LOWNER": "user@example.com",
    "XPRD01": "Updated Product",
    "XPRD02": 109.99,
    "XPRD05": "cat_123",
    "XPRD06": true
  },
  "message": "Record updated successfully",
  "event_id": "uuid-..."
}

Partial Update

PATCH /api/v4/core/{dim}/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "data": {
    "XPRD02": 89.99
  }
}

Path Parameters:

{dim} - Dimension code
{id} - Record ID

Request Body:

data (object) - Fields to update (COD_ON_OFF containing 'M')

Response:

{
  "data": {
    "PRD_ID": 123,
    "TREC": "M",
    "LDATA": "20251219175500",
    "LOWNER": "user@example.com",
    "XPRD01": "Updated Product",
    "XPRD02": 89.99
  },
  "message": "Record partially updated",
  "event_id": "uuid-..."
}

Soft Delete

DELETE /api/v4/core/{dim}/{id}
Authorization: Bearer {token}

Path Parameters:

{dim} - Dimension code
{id} - Record ID

Response:

{
  "data": {
    "PRD_ID": 123,
    "TREC": "C",
    "LDATA": "20251219180000",
    "LOWNER": "user@example.com"
  },
  "message": "Record soft deleted",
  "event_id": "uuid-..."
}

Force Delete

DELETE /api/v4/core/{dim}/{id}?force=true
Authorization: Bearer {token}

Path Parameters:

{dim} - Dimension code
{id} - Record ID

Query Parameters:

force=true - Physically remove record

Response:

{
  "message": "Record permanently deleted",
  "record_id": 123,
  "event_id": "uuid-..."
}

Metadata Endpoints

Get Dimension Metadata

GET /api/v4/core/DIM/{dim}
Authorization: Bearer {token}

Response:

{
  "data": {
    "COD_DIM": "PRD",
    "DESC_DIM": "Products",
    "TABLE_NAME": "TB_ANAG_PRD00",
    "ID_FIELD": "PRD_ID",
    "CASCADE_DELETE": "PRDIMG,PRDCAT"
  }
}

Get Field Definitions

GET /api/v4/core/VAR?filter[COD_DIM]={dim}
Authorization: Bearer {token}

Response:

{
  "data": [
    {
      "COD_DIM": "PRD",
      "NUM_VAR": 1,
      "COD_VAR": "XPRD01",
      "DESC_VAR": "Product Name",
      "DATA_TYPE": "VARCHAR",
      "LENGTH": 255,
      "NULLABLE": false
    }
  ]
}

Get Field Configurations

GET /api/v4/core/COST?filter[COD_DIM]={dim}
Authorization: Bearer {token}

Response:

{
  "data": [
    {
      "COD_DIM": "PRD",
      "NUM_COST": 1,
      "COD_VAR": "XPRD01",
      "COD_ON_OFF": "LDRNM",
      "REQUIRED": true,
      "RENDER_HINT": "text",
      "GROUP_NAME": "Basic Info"
    }
  ]
}

Get Field Metadata (Combined)

GET /api/v4/core/{dim}/fields
Authorization: Bearer {token}

Response (combines TB_VAR + TB_COST):

{
  "data": [
    {
      "cod_var": "XPRD01",
      "desc_var": "Product Name",
      "data_type": "VARCHAR",
      "length": 255,
      "cod_on_off": "LDRNM",
      "required": true,
      "render_hint": "text",
      "group_name": "Basic Info"
    }
  ]
}

Count Records

GET /api/v4/core/{dim}/count
Authorization: Bearer {token}

Query Parameters: Same filters as list endpoint

Response:

{
  "count": 156,
  "dimension": "PRD",
  "filters_applied": {
    "XPRD05": "electronics",
    "TREC": { "$ne": "C" }
  }
}

Media Endpoints

Upload File

POST /api/v4/media/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

file: [binary data]
dimension: PRD
record_id: 123
field: XPRD_IMAGE

Response:

{
  "file_id": "uuid-...",
  "url": "/api/v4/media/PRD/123/XPRD_IMAGE",
  "size": 245678,
  "mime_type": "image/jpeg",
  "uploaded_at": "20251219180000"
}

Get Media File

GET /api/v4/media/{dim}/{id}/{field}
Authorization: Bearer {token}

Path Parameters:

{dim} - Dimension code
{id} - Record ID
{field} - Media field name

Query Parameters:

size - Thumbnail size (thumbnail, small, medium, large)

Response: Binary file with appropriate Content-Type header

Example:

GET /api/v4/media/PRD/123/XPRD_IMAGE?size=thumbnail

# Returns JPEG image

Get Public Image

GET /api/v4/media/public/{dim}/{id}/{field}

No authentication required (public images only)

Batch Operations

Batch Create

POST /api/v4/core/{dim}/batch
Authorization: Bearer {token}
Content-Type: application/json

{
  "data": [
    { "XPRD01": "Product 1", "XPRD02": 99.99 },
    { "XPRD01": "Product 2", "XPRD02": 89.99 },
    { "XPRD01": "Product 3", "XPRD02": 79.99 }
  ]
}

Response:

{
  "success": 3,
  "failed": 0,
  "results": [
    { "id": 124, "status": "created" },
    { "id": 125, "status": "created" },
    { "id": 126, "status": "created" }
  ]
}

Batch Update

PATCH /api/v4/core/{dim}/batch
Authorization: Bearer {token}
Content-Type: application/json

{
  "data": [
    { "id": 123, "XPRD02": 89.99 },
    { "id": 124, "XPRD02": 79.99 }
  ]
}

Response:

{
  "success": 2,
  "failed": 0,
  "results": [
    { "id": 123, "status": "updated" },
    { "id": 124, "status": "updated" }
  ]
}

Batch Delete

POST /api/v4/core/{dim}/batch-delete
Authorization: Bearer {token}
Content-Type: application/json

{
  "ids": [123, 124, 125],
  "force": false
}

Response:

{
  "success": 3,
  "failed": 0,
  "results": [
    { "id": 123, "status": "deleted" },
    { "id": 124, "status": "deleted" },
    { "id": 125, "status": "deleted" }
  ]
}

Advanced Queries

Complex Filtering

GET /api/v4/core/PRD?\
  filter[XPRD05]=electronics&\
  filter[XPRD02][$between]=50,150&\
  filter[XPRD06]=true&\
  filter[CREATED_AT][$gte]=20251201000000&\
  sort=-XPRD02&\
  $num_rows=50&\
  $fields=XPRD01,XPRD02,XPRD05
Authorization: Bearer {token}

Filters Applied:

Category = electronics
Price between $50 and $150
Active = true
Created after Dec 1, 2025
Sort by price (descending)
Limit to 50 records
Return only name, price, category

Field Selection with Expansion

GET /api/v4/core/ORD?\
  $fields=XORD01,XORD_TOTAL,XORD_STATUS&\
  $expand=customer,items&\
  filter[XORD_STATUS]=pending&\
  sort=-CREATED_AT&\
  $num_rows=20
Authorization: Bearer {token}

Response:

{
  "data": [
    {
      "ORD_ID": 456,
      "XORD01": "ORD-2025-001",
      "XORD_TOTAL": 299.99,
      "XORD_STATUS": "pending",
      "customer": {
        "CUST_ID": "cust_789",
        "XCUST01": "John Doe",
        "XCUST_EMAIL": "john@example.com"
      },
      "items": [
        {
          "ORDITEM_ID": 1,
          "XORDITEM10": "prd_123",
          "XORDITEM_QTY": 2,
          "XORDITEM_PRICE": 99.99
        }
      ]
    }
  ]
}

Keyset Pagination

GET /api/v4/core/PRD?\
  filter[PRD_ID][$gt]=1000&\
  sort=PRD_ID&\
  $num_rows=100
Authorization: Bearer {token}

Next Page:

GET /api/v4/core/PRD?\
  filter[PRD_ID][$gt]=1100&\
  sort=PRD_ID&\
  $num_rows=100
Authorization: Bearer {token}

Error Responses

Standard Error Format

{
  "error": "ErrorType",
  "message": "Human-readable error message",
  "code": "ERROR_CODE",
  "status": 400,
  "field": "XPRD05",
  "details": {
    "additional": "context"
  }
}

Common Status Codes

Status	Error	Description
200	-	Success
201	-	Created
400	Bad Request	Invalid request syntax
401	Unauthorized	Missing or invalid token
403	Forbidden	Insufficient permissions
404	Not Found	Dimension or record not found
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
502	Bad Gateway	Backend unavailable
503	Service Unavailable	Maintenance mode

Validation Error

{
  "error": "ValidationError",
  "message": "Required field missing: XPRD05",
  "code": "REQUIRED_FIELD_MISSING",
  "status": 422,
  "field": "XPRD05"
}

Permission Error

{
  "error": "PermissionDenied",
  "message": "User lacks required grant: products.write",
  "code": "INSUFFICIENT_PERMISSIONS",
  "status": 403,
  "required_grant": "products.write",
  "user_grants": ["products.read"]
}

Rate Limit Error

{
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded. Retry after 300 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "status": 429,
  "retry_after": 300,
  "limit": 1000,
  "remaining": 0,
  "reset": 1735574400
}

Response Headers

Standard Headers

Content-Type: application/json
X-Request-ID: uuid-...
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1735574400

CORS Headers

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 86400

Summary

✅ RESTful endpoints for CRUD operations on all dimensions
✅ Metadata endpoints for runtime schema discovery
✅ Media endpoints for binary file handling
✅ Batch operations for bulk create/update/delete
✅ Advanced filtering with operators and field selection
✅ Consistent error responses with clear status codes
✅ Authentication required via JWT Bearer token

Key Patterns:

GET /api/v4/core/{dim} - List records
GET /api/v4/core/{dim}/{id} - Single record
POST /api/v4/core/{dim} - Create record
PUT /api/v4/core/{dim}/{id} - Full update
PATCH /api/v4/core/{dim}/{id} - Partial update
DELETE /api/v4/core/{dim}/{id} - Soft delete
DELETE /api/v4/core/{dim}/{id}?force=true - Force delete

Query Parameters:

$num_rows, $offset - Pagination
$fields - Field selection
$expand - Include relations
filter[field][$operator] - Filtering
sort - Sorting

API Operations - Detailed operation guides
Query Patterns - Advanced filtering
Write Patterns - Create/update/delete
Error Codes - Complete error reference
Quick Reference - Cheat sheet

API Endpoints

Overview​

Authentication​

Required Header​

Token Endpoints​

Login​

Refresh Token​

Custom Headers​

canary-mode​

developer​

microservice​

Combining Custom Headers​

Custom Headers Summary​

CRUD Operations​

List Records (Collection)​

Get Single Record​

Create Record​

Full Update​

Partial Update​

Soft Delete​

Force Delete​

Metadata Endpoints​

Get Dimension Metadata​

Get Field Definitions​

Get Field Configurations​

Get Field Metadata (Combined)​

Count Records​

Media Endpoints​

Upload File​

Get Media File​

Get Public Image​

Batch Operations​

Batch Create​

Batch Update​

Batch Delete​

Advanced Queries​

Complex Filtering​

Field Selection with Expansion​

Keyset Pagination​

Error Responses​

Standard Error Format​

Common Status Codes​

Validation Error​

Permission Error​

Rate Limit Error​

Response Headers​

Standard Headers​

CORS Headers​

Summary​

Related Concepts​

Overview

Authentication

Required Header

Token Endpoints

Login

Refresh Token

Custom Headers

canary-mode

developer

microservice

Combining Custom Headers

Custom Headers Summary

CRUD Operations

List Records (Collection)

Get Single Record

Create Record

Full Update

Partial Update

Soft Delete

Force Delete

Metadata Endpoints

Get Dimension Metadata

Get Field Definitions

Get Field Configurations

Get Field Metadata (Combined)

Count Records

Media Endpoints

Upload File

Get Media File

Get Public Image

Batch Operations

Batch Create

Batch Update

Batch Delete

Advanced Queries

Complex Filtering

Field Selection with Expansion

Keyset Pagination

Error Responses

Standard Error Format

Common Status Codes

Validation Error

Permission Error

Rate Limit Error

Response Headers

Standard Headers

CORS Headers

Summary

Related Concepts