Skip to main content

Introduction to Q01 Core APIs

Welcome​

Q01 Core APIs represent the semantic data access layer of the Q01 platform - a sophisticated metadata-driven system that abstracts data operations across multi-tenant, multi-database environments while enforcing comprehensive security and validation rules.

This documentation is designed for senior developers and software architects who need to understand, integrate with, or extend Q01 Core APIs.

What Are Q01 Core APIs?​

Q01 Core APIs are not simple CRUD wrappers around database tables. They are an intelligent data access platform that:

  • Interprets metadata at runtime to dynamically construct queries, validate data, and enforce business rules
  • Abstracts database technology (MySQL, Oracle) behind a consistent API surface
  • Enforces multi-level security through permissions, field visibility, and context-aware access control
  • Maintains multi-tenant isolation while sharing metadata infrastructure
  • Implements CQRS pattern internally for optimized read and write operations
  • Guarantees consistency across distributed systems using the outbox pattern for event sourcing

Critical Architectural Understanding​

CoreService: The Single Entry Point​

All applications interact exclusively with CoreService - the public-facing API gateway. CoreService endpoints accept standard HTTP methods (GET, POST, PUT, PATCH, DELETE) and automatically route to internal backends:

  • GET requests → Routed to CoreQuery (read-optimized backend)
  • POST/PUT/PATCH/DELETE requests → Routed to CoreWrite (write-optimized backend)

This internal routing is completely transparent to API consumers. You never call CoreQuery or CoreWrite directly.

┌─────────────────┐
│   Application   │
└────────┬────────┘
         │
         │ HTTP: GET /api/v4/core/products
         │
         v
┌────────────────────────┐
│     CoreService        │  ← ONLY public-facing API
│   (API Gateway)        │
└─────────┬──────────────┘
          │
    ┌─────┴─────┐
    │           │
    v           v
┌─────────┐ ┌──────────┐
│CoreQuery│ │CoreWrite │  ← Internal backends
│(Reads)  │ │(Writes)  │     (transparent to users)
└─────────┘ └──────────┘

The Metadata-Driven Paradigm​

Unlike traditional APIs where endpoints are hardcoded for specific entities, Q01 Core APIs use a metadata-first approach:

  1. Define once in metadata - Register dimensions (entity types), fields, relationships, permissions in metadata tables (TB_DIM, TB_COST, TB_VAR, etc.)
  2. APIs adapt automatically - Core APIs interpret metadata at request time to build queries, validate data, and enforce rules
  3. Zero code deployment - Add new entity types, fields, or permissions by updating metadata, not deploying code

This enables unprecedented flexibility while maintaining consistency and security.

Who Should Use This Documentation?​

This documentation is for:

  • Backend developers integrating applications with Q01 Core APIs
  • Solution architects designing Q01-based systems
  • Platform engineers extending or maintaining Q01 infrastructure
  • Technical leads evaluating Q01 for multi-tenant SaaS platforms

Prerequisites​

We assume you have:

  • Strong understanding of REST APIs and HTTP protocols
  • Experience with relational databases (SQL, transactions, normalization)
  • Familiarity with JWT authentication and authorization patterns
  • Understanding of multi-tenant SaaS architecture concepts

What You'll Learn​

By the end of this documentation, you will:

  1. Understand Q01's metadata-driven architecture and the MAP framework
  2. Know how to query data using filtering, sorting, projections, and relational queries
  3. Know how to create, update, and delete entities with proper validation
  4. Understand the context chain (source, center_dett, peso, ambiente) and how it affects operations
  5. Implement field visibility correctly using COD_ON_OFF flags
  6. Design metadata for new dimensions (entity types)
  7. Configure cascades, counters, and pre-insert functions
  8. Avoid common anti-patterns that lead to security or consistency issues
  9. Troubleshoot permission and validation failures

Documentation Structure​

This documentation is organized in progressive disclosure:

1. Introduction (You Are Here)​

High-level overview of Q01 Core APIs, architecture, and philosophy.

2. Core Concepts ⭐ CRITICAL​

Deep dive into the 12 fundamental concepts you must understand:

  • Dimensions, MAP framework, context chain, COD_ON_OFF, permissions, TREC lifecycle, cascades, outbox pattern, counters, and more

Start here if you're new to Q01. Everything else builds on these concepts.

3. API Operations​

How to perform operations via CoreService endpoints:

  • Read operations (GET)
  • Write operations (POST, PUT, PATCH, DELETE)
  • Media operations
  • Special operations (sort, commands)

4. Query Patterns​

Advanced querying techniques:

  • Filtering with $filter
  • Sorting and grouping
  • Pagination and projection
  • Relational queries
  • Document queries

5. Write Patterns​

Creating, updating, and deleting data:

  • Validation model
  • Cascades
  • Transactions
  • Outbox pattern for consistency

6. Security​

Authentication, authorization, and tenant isolation:

  • JWT authentication
  • Grant system
  • Multi-level permissions
  • Field-level access control

7. Advanced Topics​

Specialized features and internal architecture:

  • Multi-database support
  • Counter configuration
  • Media handling (Google Cloud Storage)
  • Event sourcing internals
  • Custom views

8. Best Practices​

Guidelines for correct usage:

  • When to use Core APIs
  • Anti-patterns to avoid
  • Performance optimization
  • Security checklist

9. Reference​

Technical specifications:

  • Metadata table schemas
  • COD_ON_OFF flags
  • API endpoints
  • Error codes
  • Glossary

Getting Help​

If you encounter issues or have questions:

  1. Check the Best Practices - many common issues are covered there
  2. Review Core Concepts - ensure you understand the fundamentals
  3. Consult the Reference - for specific technical details
  4. Contact Q01 Platform Support - for assistance with complex scenarios

Next Steps​

Ready to dive in?

  1. New to Q01? → Start with Core Concepts - don't skip this!
  2. Need to query data? → Go to API Operations - Read
  3. Need to create/update data? → Go to API Operations - Write
  4. Troubleshooting? → Check Best Practices - Anti-Patterns

Let's build something amazing with Q01 Core APIs! 🚀