API Operations

Overview

This section documents how to perform all operations via CoreService - the single public-facing API gateway for Q01 Core APIs.

Key Principle:

All applications interact exclusively with CoreService endpoints. Internal routing to CoreQuery (reads) or CoreWrite (writes) is transparent - you never call them directly.

CoreService Entry Point

Base URL Pattern

https://{host}/api/v{version}/core/{dimension}

Components:

{host}: CoreService hostname (e.g., coreservice.q01.io)
{version}: API version (e.g., v4)
{dimension}: Dimension code from TB_DIM (e.g., PRD, ORD, CLI)

Examples:

https://coreservice.q01.io/api/v4/core/PRD
https://coreservice.q01.io/api/v4/core/ORD/555
https://coreservice.q01.io/api/v4/core/CLI?$filter=XCLI01 eq 'ACME'

HTTP Methods = Operations

CoreService uses RESTful HTTP methods to determine operations:

HTTP Method	Operation	Routes To	Example
GET	Read (list/detail)	CoreQuery	`GET /api/v4/core/PRD`
POST	Create	CoreWrite	`POST /api/v4/core/PRD`
PUT	Full update	CoreWrite	`PUT /api/v4/core/PRD/123`
PATCH	Partial update	CoreWrite	`PATCH /api/v4/core/PRD/123`
DELETE	Delete (soft/hard)	CoreWrite	`DELETE /api/v4/core/PRD/123`

Critical Understanding:

You make a single HTTP request to CoreService. The HTTP method determines whether CoreService routes internally to CoreQuery (GET) or CoreWrite (POST/PUT/PATCH/DELETE). This routing is completely transparent.

Operation Categories

1. Read Operations (GET)

Purpose: Query data with filtering, sorting, pagination, field selection.

Endpoint: GET /api/v4/core/{DIM}

Key Features:

List all records or single record by ID
Filter with $filter operators
Sort with $order
Paginate with $num_rows and $offset
Select fields with $select
Join related dimensions

Documentation: Read Operations →

2. Write Operations (POST/PUT/PATCH/DELETE)

Purpose: Create, update, delete data with validation, cascades, and outbox publishing.

Endpoints:

POST /api/v4/core/{DIM} - Create
PUT /api/v4/core/{DIM}/{ID} - Full update
PATCH /api/v4/core/{DIM}/{ID} - Partial update
DELETE /api/v4/core/{DIM}/{ID} - Delete

Key Features:

Automatic TREC management
Pre-insert functions
Cascade operations
Outbox event publishing
Transaction guarantees

Documentation: Write Operations →

3. Field Metadata Operations

Purpose: Retrieve field definitions, visibility, validation rules from TB_COST.

Endpoint: GET /api/v4/core/{DIM}/fields

Key Features:

Get field metadata for context (nuovo, modifica, visualizza)
COD_ON_OFF visibility filtering
Field types from TB_TYPE_FIELDS
Validation rules

Documentation: Field Metadata →

4. Media Operations

Purpose: Upload and retrieve images/files stored in Google Cloud Storage.

Endpoints:

POST /api/v4/core/{DIM}/media - Upload
GET /api/v4/core/{DIM}/{ID}/media/{FIELD} - Download

Key Features:

Binary file upload
Automatic GCS storage
Metadata tracking in dimension table
Public/private URL generation

Documentation: Media Operations →

5. Sort Operations

Purpose: Pre-defined sort configurations for consistent ordering.

Endpoint: GET /api/v4/core/{DIM}/sort/{SORT_KEY}

Key Features:

Named sort configurations
Multi-field ordering
ASC/DESC control

Documentation: Sort Operations →

6. Command Operations

Purpose: Special operations not fitting standard CRUD (e.g., export, import, custom logic).

Endpoint: POST /api/v4/core/{DIM}/command/{COMMAND_NAME}

Key Features:

Custom business logic
Batch operations
Data transformations
External integrations

Documentation: Command Operations →

7. Batch Operations

Purpose: Perform multiple operations in single request for efficiency.

Endpoint: POST /api/v4/core/batch

Key Features:

Multiple creates in one transaction
Bulk updates
Transaction rollback on failure

Documentation: Batch Operations →

Common Request Elements

Required Headers

Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
Accept: application/json

Required Query Parameters

For all operations:

source={SECURITY_AREA}

Example:

GET /api/v4/core/PRD?source=productList

Why source is required: Permission validation via TB_MENU nested set hierarchy.

Context Parameters

Common parameters traveling with requests:

Parameter	Purpose	Example	Required
`source`	Security area	`productList`	✅ Yes
`center_dett`	Context for field visibility	`visualizza`	Recommended
`ambiente`	Tenant isolation	Extracted from JWT	Auto
`modulo`	Module context	`Default`	Auto
`microservice`	Source microservice	`corequery`	Auto

Documentation: Context Chain →

Response Formats

Success Responses

List (GET):

[
  {"PRD_ID": "1", "XPRD01": "Widget A"},
  {"PRD_ID": "2", "XPRD01": "Widget B"}
]

Single Record (GET with ID):

{
  "PRD_ID": "123",
  "XPRD01": "Premium Widget",
  "XPRD02": 49.99
}

Create (POST):

[{
  "code": 201,
  "insertedId": "123",
  "body": {
    "XPRD01": "Premium Widget",
    "XPRD02": 49.99
  },
  "fields": {
    "PRD_ID": {...},
    "XPRD01": {...}
  }
}]

Update (PUT/PATCH):

{
  "code": 200,
  "modifiedId": "123",
  "body": {
    "XPRD02": 59.99
  }
}

Delete:

{
  "code": 200,
  "message": "Record deleted successfully",
  "deletedId": "123"
}

Error Responses

Format:

{
  "code": 400,
  "message": "Validation error",
  "errors": [
    {
      "field": "XPRD01",
      "message": "Field is required"
    }
  ]
}

Common HTTP Status Codes:

200 OK - Success
201 Created - Resource created
400 Bad Request - Validation error
401 Unauthorized - Missing/invalid JWT
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
500 Internal Server Error - Server error

Authentication

All requests require JWT authentication:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT contains:

User ID (login_id)
Grants (security area permissions)
Tenant ID (ambiente)
Session metadata

Documentation: JWT Authentication →

Permissions

Multi-layer validation:

JWT valid - Token not expired, signature valid
Source authorized - User has grant for source parameter
Grant level sufficient - User grant ≥ required grant (0-4)
Field visibility - COD_ON_OFF filtering by center_dett
Peso filtering - User peso ≥ field peso (TB_COST.COD_UTENTE)

Documentation: Multi-Level Permissions →

Operation Flow

Read Operation (GET)

┌──────────────┐
│    Client    │
└──────┬───────┘
       │ GET /api/v4/core/PRD?source=productList
       v
┌──────────────────┐
│   CoreService    │ ← Single entry point
└──────┬───────────┘
       │ Routes based on HTTP method (GET)
       v
┌──────────────────┐
│   CoreQuery      │ ← Internal backend
│  (Read Service)  │
└──────┬───────────┘
       │
       │ 1. Validate JWT & permissions
       │ 2. Load metadata (TB_DIM, TB_COST)
       │ 3. Build SQL query
       │ 4. Filter by COD_ON_OFF
       │ 5. Execute query
       │ 6. Return JSON
       │
       v
┌──────────────┐
│    Client    │ ← Receives array of records
└──────────────┘

Write Operation (POST)

┌──────────────┐
│    Client    │
└──────┬───────┘
       │ POST /api/v4/core/PRD
       │ Body: {"XPRD01": "Widget"}
       v
┌──────────────────┐
│   CoreService    │ ← Single entry point
└──────┬───────────┘
       │ Routes based on HTTP method (POST)
       v
┌──────────────────┐
│   CoreWrite      │ ← Internal backend
│  (Write Service) │
└──────┬───────────┘
       │
       │ 1. Validate JWT & permissions
       │ 2. Load metadata
       │ 3. Execute pre-insert functions
       │ 4. Validate required fields
       │ 5. BEGIN TRANSACTION
       │ 6. INSERT into dimension table
       │ 7. Execute cascades
       │ 8. Write to TB_ANAG_OUTBOX00
       │ 9. COMMIT
       │ 10. Relay publishes to RabbitMQ
       │
       v
┌──────────────┐
│    Client    │ ← Receives insertedId + metadata
└──────────────┘

Next Steps

Start with the basics:

Read Operations - Learn how to query data → Read Operations
Write Operations - Learn how to create/update/delete data → Write Operations
Field Metadata - Understand how to get field definitions → Field Metadata

Advanced topics:

Media Operations - File uploads
Sort Operations - Pre-defined sorting
Command Operations - Custom operations
Batch Operations - Bulk operations

Key Takeaways

✅ CoreService is the only public API - Never call CoreQuery/CoreWrite directly
✅ HTTP method determines operation - GET=read, POST=create, PUT=update, etc.
✅ source parameter is required - For permission validation
✅ JWT authentication mandatory - All requests must be authenticated
✅ Responses are consistent - Arrays for lists, objects for single records
✅ Internal routing is transparent - CoreService handles routing automatically

Ready to start querying data? Continue to Read Operations →

API Operations

Overview​

CoreService Entry Point​

Base URL Pattern​

HTTP Methods = Operations​

Operation Categories​

1. Read Operations (GET)​

2. Write Operations (POST/PUT/PATCH/DELETE)​

3. Field Metadata Operations​

4. Media Operations​

5. Sort Operations​

6. Command Operations​

7. Batch Operations​

Common Request Elements​

Required Headers​

Required Query Parameters​

Context Parameters​

Response Formats​

Success Responses​

Error Responses​

Authentication​

Permissions​

Operation Flow​

Read Operation (GET)​

Write Operation (POST)​

Next Steps​

Key Takeaways​

Overview

CoreService Entry Point

Base URL Pattern

HTTP Methods = Operations

Operation Categories

1. Read Operations (GET)

2. Write Operations (POST/PUT/PATCH/DELETE)

3. Field Metadata Operations

4. Media Operations

5. Sort Operations

6. Command Operations

7. Batch Operations

Common Request Elements

Required Headers

Required Query Parameters

Context Parameters

Response Formats

Success Responses

Error Responses

Authentication

Permissions

Operation Flow

Read Operation (GET)

Write Operation (POST)

Next Steps

Key Takeaways