Reference

Overview

This section provides quick lookup reference material for Q01 Core APIs, including metadata table schemas, API endpoint catalogs, error code references, COD_ON_OFF flag definitions, TREC lifecycle states, and a comprehensive glossary.

What You'll Find:

• ✅ Metadata table schemas (TB_DIM, TB_VAR, TB_COST, TB_MENU, TB_OBJECT)
• ✅ Complete API endpoint catalog with HTTP methods and parameters
• ✅ COD_ON_OFF field visibility flag reference
• ✅ TREC lifecycle state definitions
• ✅ Error codes and troubleshooting guide
• ✅ Glossary of terms and concepts
• ✅ FAQ (Frequently Asked Questions)
• ✅ Quick reference cheat sheet

Target Audience:

• Developers implementing Core API integrations
• System architects designing Q01-based applications
• Technical support troubleshooting issues
• DevOps engineers configuring deployments
• Anyone needing quick lookup of technical specifications

Reference Sections

Metadata Tables

Complete schemas for MAP framework metadata tables:

TB_DIM - Dimension Registry

• Dimension definitions and configuration
• Primary keys, prefixes, and naming conventions
• Cascade operation rules
• Default field visibility settings

TB_VAR - Field Definitions

• Field metadata for all dimensions
• Data types and validation rules
• Default values and constraints
• Field ordering and grouping

TB_COST - Field Configuration

• Field visibility (COD_ON_OFF flags)
• Required field markers
• Pre-insert functions (VALUE_TEMP)
• Cascade operation definitions
• Field rendering hints

TB_MENU - Permission Hierarchy

• Nested set model structure (NLEFT/NRIGHT)
• Grant definitions and inheritance
• Security area organization
• Permission checking queries

TB_OBJECT - Dimension Relationships

• Foreign key definitions
• Join configurations
• Related dimension mappings
• Relationship cardinality

COD_ON_OFF Flags

Complete reference for field visibility flags:

Flag	Context	Meaning	Usage
L	List	Visible in list views	GET /api/v4/core/{dim}
D	Detail	Visible in detail views	GET /api/v4/core/{dim}/{id}
N	New	Can be set on creation	POST /api/v4/core/{dim}
M	Modify	Can be updated	PUT/PATCH /api/v4/core/{dim}/{id}
R	Search	Can be used in filters	?filter[field]=$filter

Examples:

• COD_ON_OFF = "LDRNM" - Full visibility, can create and modify
• COD_ON_OFF = "LDR" - Visible and searchable, but read-only
• COD_ON_OFF = "N" - Can only be set on creation (e.g., immutable identifiers)
• COD_ON_OFF = "" - Hidden field (internal use only)

TREC Lifecycle

Record lifecycle state reference:

POST (Create)
    ↓
  TREC='N' (New)
    ↓
PUT/PATCH (Update)
    ↓
  TREC='M' (Modified)
    ↓
DELETE?force=false
    ↓
  TREC='C' (Cancelled - Soft Delete)
    ↓
DELETE?force=true
    ↓
  Physical Deletion

State Definitions:

• N (New) - Record just created, never modified
• M (Modified) - Record has been updated at least once
• C (Cancelled) - Soft deleted, excluded from queries by default
• P (Processed) - Special state for workflow processing (rare)

Filtering by TREC:

• Active records: ?filter[TREC][$ne]=C (exclude cancelled)
• Modified records only: ?filter[TREC]=M
• Include deleted: ?filter[TREC][$in]=N,M,C

API Endpoints

Complete catalog of Core API endpoints:

Read Operations (GET):

• GET /api/v4/core/{dim} - List records
• GET /api/v4/core/{dim}/{id} - Get single record
• GET /api/v4/core/{dim}/fields - Get field metadata
• GET /api/v4/core/{dim}/count - Count records

Write Operations (POST/PUT/PATCH/DELETE):

• 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} - Delete record

Media Operations:

• POST /api/v4/media/upload - Upload binary file
• GET /api/v4/media/{dim}/{id}/{field} - Retrieve media

Query Parameters:

• Filtering: ?filter[field][$operator]=value
• Sorting: ?sort=field1,-field2
• Pagination: ?$num_rows=100&$offset=0
• Field selection: ?$fields=field1,field2
• Expansion: ?$expand=relation1,relation2

Error Codes

Common HTTP status codes and error responses:

4xx Client Errors:

• 400 Bad Request - Invalid request syntax or parameters
• 401 Unauthorized - Missing or invalid JWT token
• 403 Forbidden - Valid token but insufficient permissions
• 404 Not Found - Dimension or record does not exist
• 422 Unprocessable Entity - Validation error (missing required fields)
• 429 Too Many Requests - Rate limit exceeded

5xx Server Errors:

• 500 Internal Server Error - Unexpected server error
• 502 Bad Gateway - Backend service unavailable
• 503 Service Unavailable - Server overloaded or maintenance
• 504 Gateway Timeout - Backend did not respond in time

Error Response Format:

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

Glossary

Terms and definitions:

• Dimension (DIM) - Business entity type (e.g., PRD = Products, ORD = Orders)
• MAP Framework - Metadata-driven architecture (TB_DIM, TB_VAR, TB_COST, TB_MENU, TB_OBJECT)
• Context Chain - Request context (source/peso/ambiente/centro_dett/modulo/lingua)
• COD_ON_OFF - Field visibility bitmask (L/D/N/M/R flags)
• TREC - Transaction record lifecycle state (N/M/C/P)
• Peso - User level hierarchy (1=admin, 2=manager, 3=user)
• Source - Tenant/application identifier
• Centro_dett - Organizational unit or cost center
• Ambiente - Environment (production/staging/test)
• OUTBOX - Event sourcing pattern with RabbitMQ
• Cascade - Automatic operation propagation to related dimensions
• Nested Set - TB_MENU hierarchical permission model (NLEFT/NRIGHT)

FAQ

Frequently asked questions:

General Questions:

• What is Q01 Core API?
• How does the metadata-driven approach work?
• What's the difference between CoreQuery and CoreWrite?
• How do I get started with Core APIs?

Authentication & Authorization:

• How do JWT tokens work?
• How do I refresh expired tokens?
• What are grants and how do I check them?
• How does tenant isolation work?

Data Operations:

• How do I filter records?
• What's the difference between PUT and PATCH?
• How do I soft delete vs force delete?
• How do cascade operations work?

Performance & Optimization:

• How do I optimize slow queries?
• What caching strategies should I use?
• How do I implement pagination correctly?
• How do I prevent N+1 query problems?

Troubleshooting:

• Why am I getting 401 Unauthorized?
• Why am I getting 403 Forbidden?
• Why are some fields not visible?
• Why are OUTBOX events delayed?

Quick Reference

Cheat sheet for common operations:

Authentication:

# Login and get token
POST /auth/login
{ "username": "user@example.com", "password": "..." }

# Use token in requests
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

CRUD Operations:

# Create
POST /api/v4/core/PRD
{ "data": { "XPRD01": "Product Name", "XPRD02": 99.99 } }

# Read
GET /api/v4/core/PRD/123

# Update (partial)
PATCH /api/v4/core/PRD/123
{ "data": { "XPRD02": 89.99 } }

# Delete (soft)
DELETE /api/v4/core/PRD/123

Common Filters:

# Equals
?filter[XPRD05]=electronics

# Not equals
?filter[TREC][$ne]=C

# Greater than
?filter[XPRD02][$gt]=100

# In list
?filter[XPRD05][$in]=electronics,books

# Like (pattern match)
?filter[XPRD01][$like]=Widget%

Sorting & Pagination:

# Sort ascending
?sort=XPRD01

# Sort descending
?sort=-CREATED_AT

# Paginate
?$num_rows=100&$offset=0

# Select fields
?$fields=XPRD01,XPRD02,XPRD05

When to Use This Section

During Development:

• Look up metadata table schemas when designing dimensions
• Check COD_ON_OFF flags when implementing field visibility
• Reference API endpoints when building integrations
• Consult error codes when handling exceptions

During Debugging:

• Check TREC lifecycle when troubleshooting record states
• Review error codes when diagnosing API failures
• Consult FAQ for common issues
• Use quick reference for correct query syntax

During Code Review:

• Verify correct COD_ON_OFF usage
• Validate context chain completeness
• Check proper TREC state transitions
• Ensure metadata-driven patterns

During Onboarding:

• Read glossary to understand terminology
• Review API endpoints catalog
• Study metadata table schemas
• Check FAQ for common questions

Organization

Reference pages are organized by type of information:

1. Schemas - Structural definitions (metadata tables, database schema)
2. Catalogs - Complete listings (API endpoints, error codes)
3. Definitions - Term meanings (glossary, COD_ON_OFF flags, TREC states)
4. Guides - How-to references (quick reference, FAQ)

Each page is designed for quick lookup - you should be able to find specific technical details in under 30 seconds.

Cross-References

For conceptual understanding of these references, see:

• Core Concepts - Foundational concepts explained
• API Operations - How to use API endpoints
• Query Patterns - Advanced filtering and retrieval
• Write Patterns - Data modification operations
• Security - Authentication and authorization details
• Advanced Topics - Internal architecture and optimization
• Best Practices - Usage guidelines and patterns

Summary

• ✅ Reference section provides quick lookup for technical details
• ✅ Metadata tables (TB_DIM, TB_VAR, TB_COST, TB_MENU, TB_OBJECT) documented
• ✅ Complete API endpoint catalog with parameters
• ✅ COD_ON_OFF flags and TREC lifecycle states defined
• ✅ Error codes and troubleshooting guide available
• ✅ Glossary explains all Q01-specific terminology
• ✅ FAQ answers common questions
• ✅ Quick reference provides copy-paste examples

Key Takeaways:

1. Use reference for quick technical lookups during development
2. Metadata tables are the foundation of Q01's metadata-driven architecture
3. COD_ON_OFF controls field visibility across operations
4. TREC tracks record lifecycle (N→M→C)
5. Error codes help diagnose issues quickly
6. Glossary clarifies Q01-specific terminology

Next Steps

1. Browse Metadata Tables - Understand MAP framework schemas
2. Check COD_ON_OFF Flags - Learn field visibility control
3. Review TREC Lifecycle - Understand record states
4. Explore API Endpoints - See complete endpoint catalog
5. Consult Error Codes - Troubleshoot issues
6. Read Glossary - Clarify terminology
7. Check FAQ - Find answers to common questions
8. Use Quick Reference - Get copy-paste examples

---

Reference Material: For developers and architects who need quick access to technical specifications, schemas, and troubleshooting information.