Microservices

Why DTL for Microservices?

API Response Format

Use DTL as your API response format for type-safe, compact responses:

@dtlv1.0^dtWEB^pAPIv1^c0^s0^w0^responsehash
@sec^none^0x0^none^0

# Response metadata
META|request_id:s,status:e(success,error,partial),timestamp:T,duration_ms:i|1|S0|W0|C0
req-abc123|success|2025-01-03T10:30:00Z|45

# Actual data
USERS|id:s,name:s,email:s,role:e(admin,user,guest),active:b|3|S0|W0|C0
U001|Alice Smith|alice@example.com|admin|1
U002|Bob Johnson|bob@example.com|user|1
U003|Carol White|carol@example.com|guest|0

# Pagination
PAGINATION|page:i,per_page:i,total:i,has_more:b|1|S0|W0|C0
1|20|150|1

Service-to-Service Communication

Request/Response Pattern

# Order Service → Payment Service
@dtlv1.0^dtWEB^pPaymentRequest^c0^s1^w0^reqhash
@sec^blake3^0x0^none^0

REQUEST|id:s,source:s,target:s,action:e(charge,refund,verify),timestamp:T|1|S1|W0|C0
req-12345|order-service|payment-service|charge|2025-01-03T10:00:00Z

PAYMENT|order_id:s,amount:f,currency:e(USD,EUR,AED),customer:s,method:e(card,bank,wallet)|1|S1|W0|C0
ORD-789|99.99|USD|CUST-456|card

# Payment Service → Order Service
@dtlv1.0^dtWEB^pPaymentResponse^c0^s1^w0^reshash
@sec^blake3^0x0^none^0

RESPONSE|request_id:s,status:e(success,failed,pending),timestamp:T|1|S1|W0|C0
req-12345|success|2025-01-03T10:00:05Z

RESULT|transaction_id:s,amount:f,currency:e(USD,EUR,AED),status:e(captured,authorized,declined)|1|S1|W0|C0
TXN-ABC123|99.99|USD|captured

Event Streaming

DTL's line-by-line format is perfect for event streaming:

Event Schema

@dtlv1.0^dtWEB^pEventStream^c0^s1^w0^streamhash
@sec^blake3^0x0^none^0

# Event header - defines the event type
EVENTS|id:s,type:e(user.created,user.updated,user.deleted,order.placed,order.shipped,order.delivered),source:s,timestamp:T,data:j|0|S1|W0|C0

Streaming Events

# Each line is one event - can be streamed/appended
evt-001|user.created|auth-service|2025-01-03T10:00:00Z|{"user_id":"U001","email":"alice@example.com"}
evt-002|order.placed|order-service|2025-01-03T10:00:05Z|{"order_id":"ORD-001","user_id":"U001","total":99.99}
evt-003|user.updated|profile-service|2025-01-03T10:00:10Z|{"user_id":"U001","name":"Alice Smith"}
evt-004|order.shipped|shipping-service|2025-01-03T10:30:00Z|{"order_id":"ORD-001","carrier":"FedEx"}
evt-005|order.delivered|shipping-service|2025-01-03T14:00:00Z|{"order_id":"ORD-001"}

Consumer Code

from dtl_parser import DTLParser
import json

parser = DTLParser()

# Stream events line by line
with open("events.dtl") as f:
    # Skip headers
    for _ in range(3):
        next(f)
    
    # Process events
    for line in f:
        parts = line.strip().split("|")
        event = {
            "id": parts[0],
            "type": parts[1],    # Validated by enum!
            "source": parts[2],
            "timestamp": parts[3],
            "data": json.loads(parts[4])
        }
        handle_event(event)

API Contract Definition

Use DTL to define your API contracts with strict typing:

@dtlv1.0^dtWEB^pAPIContract^c0^s0^w0^contracthash
@sec^none^0x0^none^0

# ═══════════════════════════════════════════════════════
# API: User Service v1
# Base URL: https://api.example.com/v1/users
# ═══════════════════════════════════════════════════════

# Endpoint definitions
ENDPOINTS|path:s,method:e(GET,POST,PUT,PATCH,DELETE),description:s,auth:b|5|S0|W0|C0
/users|GET|List all users with pagination|1
/users|POST|Create a new user|1
/users/{id}|GET|Get user by ID|1
/users/{id}|PUT|Update user|1
/users/{id}|DELETE|Delete user|1

# Request schemas
CREATE_USER_REQ|field:s,type:s,required:b,description:s|4|S0|W0|C0
name|s|1|User's full name
email|s|1|Email address (unique)
role|e(admin,user,guest)|1|User role
active|b|0|Account status (default: true)

# Response schemas
USER_RES|field:s,type:s,description:s|5|S0|W0|C0
id|s|Unique user ID
name|s|Full name
email|s|Email address
role|e(admin,user,guest)|User role
created_at|T|Creation timestamp

# Error codes
ERRORS|code:i,type:e(validation,auth,not_found,server),message:s|4|S0|W0|C0
400|validation|Invalid request body
401|auth|Authentication required
404|not_found|User not found
500|server|Internal server error

Service Health & Metrics

@dtlv1.0^dtWEB^pHealthCheck^c0^s0^w0^healthhash
@sec^none^0x0^none^0

# Service health status
HEALTH|service:s,status:e(healthy,degraded,unhealthy),uptime_seconds:i,last_check:T|5|S0|W0|C0
api-gateway|healthy|86400|2025-01-03T10:00:00Z
user-service|healthy|86000|2025-01-03T10:00:00Z
order-service|degraded|85000|2025-01-03T10:00:00Z
payment-service|healthy|84000|2025-01-03T10:00:00Z
notification-service|unhealthy|0|2025-01-03T09:55:00Z

# Dependency checks
DEPENDENCIES|service:s,dependency:s,status:e(ok,slow,down),latency_ms:i|6|S0|W0|C0
user-service|postgres|ok|5
user-service|redis|ok|2
order-service|postgres|slow|250
order-service|kafka|ok|10
payment-service|stripe-api|ok|150
notification-service|smtp|down|0

Configuration Management

@dtlv1.0^dtWEB^pServiceConfig^c0^s1^w0^confighash
@sec^blake3^0x0^none^0

# Environment-specific config
CONFIG|key:s,value:s,env:e(dev,staging,prod),encrypted:b|8|S1|W0|C0
database_url|postgres://dev-db:5432/app|dev|0
database_url|postgres://staging-db:5432/app|staging|0
database_url|postgres://prod-db-cluster:5432/app|prod|1
redis_url|redis://localhost:6379|dev|0
redis_url|redis://staging-redis:6379|staging|0
redis_url|redis://prod-redis-cluster:6379|prod|1
api_key|dev-key-123|dev|0
api_key|[ENCRYPTED]|prod|1

# Feature flags
FEATURES|name:s,status:e(enabled,disabled,percentage),value:s,env:e(dev,staging,prod,all)|4|S0|W0|C0
new_checkout|enabled||dev
new_checkout|percentage|25|staging
new_checkout|disabled||prod
dark_mode|enabled||all

Integration Patterns

Service A → DTL Request → Service B
Service A ← DTL Response ← Service B

Producer → DTL Event → Message Queue
Message Queue → DTL Event → Consumer

Source → DTL File → S3/Storage
Storage → DTL File → Processor

Sidecar validates DTL schemas
Circuit breaker on validation errors

SDK Integration Examples

Implement DTL-based microservices communication with validation:

🐍 Python - FastAPI Service

from fastapi import FastAPI, HTTPException
from dtl_parser import DTLParser, create_table, validate

app = FastAPI()
parser = DTLParser()

# Define API response schema
response_schema = create_table("RESPONSE", {
    "code": "i",
    "status": "e(success,error,pending)",
    "message": "s",
    "data": "j",
})

@app.post("/api/orders")
async def create_order(dtl_request: str):
    # Parse incoming DTL
    doc = parser.parse(dtl_request)
    
    # Validate enum values
    errors = doc.validate()
    if errors:
        return build_dtl_response(400, "error", errors[0].message)
    
    # Process order...
    order = doc.get_table("ORDER")
    
    # Build DTL response
    return build_dtl_response(200, "success", "Order created")

def build_dtl_response(code: int, status: str, message: str):
    response_schema.rows = [{
        "code": code,
        "status": status,
        "message": message,
        "data": "{}"
    }]
    return response_schema.to_dtl()

📘 TypeScript - Express.js Service

import express from 'express';
import { parse, validate, createTable, tableToDtl } from 'dtl-parser';

const app = express();
app.use(express.text({ type: 'application/dtl' }));

// Order schema with enum validation
const orderSchema = createTable('ORDERS', {
    id: 'u',
    customer_id: 's',
    status: 'e(pending,confirmed,processing,shipped,delivered,cancelled)',
    priority: 'e(low,normal,high,urgent)',
    total: 'f',
});

app.post('/api/orders', (req, res) => {
    const doc = parse(req.body);
    const errors = validate(doc);
    
    if (errors.length > 0) {
        const errorResponse = createTable('ERROR', {
            code: 'i',
            type: 'e(validation,auth,server)',
            message: 's',
            suggestion: 's',
        });
        errorResponse.rows.push({
            code: 400,
            type: 'validation',
            message: errors[0].message,
            suggestion: errors[0].suggestion || '',
        });
        return res.status(400)
            .contentType('application/dtl')
            .send(tableToDtl(errorResponse));
    }
    
    // Process valid order...
    res.contentType('application/dtl').send(buildSuccessResponse());
});

// Health check endpoint
app.get('/health', (req, res) => {
    const health = createTable('HEALTH', {
        service: 's',
        status: 'e(healthy,degraded,unhealthy)',
        uptime: 'i',
        timestamp: 'T',
    });
    health.rows.push({
        service: 'order-service',
        status: 'healthy',
        uptime: process.uptime(),
        timestamp: new Date().toISOString(),
    });
    res.contentType('application/dtl').send(tableToDtl(health));
});

💜 C# - ASP.NET Core Service

using Dtlaz.Parser;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly DtlParser _parser = new();
    
    [HttpPost]
    [Consumes("application/dtl")]
    [Produces("application/dtl")]
    public IActionResult CreateOrder([FromBody] string dtlContent)
    {
        var doc = _parser.Parse(dtlContent);
        var errors = doc.Validate();
        
        if (errors.Any())
        {
            return BadRequest(BuildErrorResponse(errors.First()));
        }
        
        // Process order...
        var order = doc.GetTable("ORDER");
        
        return Ok(BuildSuccessResponse("Order created"));
    }
    
    [HttpGet("health")]
    [Produces("application/dtl")]
    public IActionResult Health()
    {
        var health = DtlFactory.CreateTable("HEALTH", 
            new Dictionary<string, string>
        {
            { "service", "s" },
            { "status", "e(healthy,degraded,unhealthy)" },
            { "dependencies", "j" },
        });
        
        health.AddRow(new Dictionary<string, object?>
        {
            { "service", "order-service" },
            { "status", "healthy" },
            { "dependencies", "{\"db\":\"ok\",\"cache\":\"ok\"}" },
        });
        
        return Ok(health.ToDtl());
    }
    
    private string BuildErrorResponse(ValidationError error)
    {
        var table = DtlFactory.CreateTable("ERROR", 
            new Dictionary<string, string>
        {
            { "code", "i" },
            { "type", "e(validation,auth,server,not_found)" },
            { "message", "s" },
            { "suggestion", "s" },
        });
        
        table.AddRow(new Dictionary<string, object?>
        {
            { "code", 400 },
            { "type", "validation" },
            { "message", error.Message },
            { "suggestion", error.Suggestion ?? "" },
        });
        
        return table.ToDtl();
    }
}