REST APIs - Audit Trail Platform (ATP)¶

APIs as contracts — ATP's REST APIs provide precise, versioned, and testable HTTP interfaces with OpenAPI 3.0 specifications, comprehensive validation, and enterprise-grade security for all audit trail operations.

📋 Documentation Generation Plan¶

This document will be generated in 10 cycles. Current progress:

Cycle	Topics	Estimated Lines	Status
Cycle 1	OpenAPI Fundamentals & API Architecture (1-2)	~2,500	⏳ Not Started
Cycle 2	Ingestion API Specifications (3-4)	~3,000	⏳ Not Started
Cycle 3	Query API Specifications (5-6)	~3,500	⏳ Not Started
Cycle 4	Policy API Specifications (7-8)	~2,500	⏳ Not Started
Cycle 5	Export API Specifications (9-10)	~2,500	⏳ Not Started
Cycle 6	Admin & Control Plane APIs (11-12)	~2,000	⏳ Not Started
Cycle 7	Authentication & Authorization (13-14)	~2,500	⏳ Not Started
Cycle 8	Error Handling & Validation (15-16)	~2,000	⏳ Not Started
Cycle 9	Pagination, Filtering & Performance (17-18)	~2,500	⏳ Not Started
Cycle 10	Versioning, Testing & Observability (19-20)	~2,500	⏳ Not Started

Total Estimated Lines: ~25,500

Purpose & Scope¶

This document provides complete OpenAPI 3.0 specifications for all REST APIs in the Audit Trail Platform (ATP), defining HTTP endpoints, request/response schemas, authentication, authorization, error handling, rate limiting, and usage patterns to ensure consistent, secure, and well-documented synchronous integrations with ATP services.

Key REST API Principles - OpenAPI 3.0: Industry-standard REST API specification format - RESTful Design: Resource-oriented URLs, HTTP verbs, stateless - Contract-First: APIs designed before implementation - Versioned: All APIs versioned (URI: /api/v1, /api/v2) - Authenticated: OAuth 2.0 Bearer tokens, Azure AD integration - Tenant-Scoped: Multi-tenancy via X-Tenant-Id header - Rate Limited: Per-tenant quotas with 429 responses - Idempotent: Write operations support Idempotency-Key header

What this document covers

Establish ATP's REST API architecture: Gateway, routing, versioning, security model
Define Ingestion API: POST endpoints for single and batch audit event ingestion
Specify Query API: GET and POST endpoints for searching, filtering, and retrieving events
Document Policy API: CRUD operations for tenant policies (classification, retention, access)
Detail Export API: Endpoints for requesting, tracking, and downloading exports
Describe Admin API: Control plane operations for projector management, DLQ, schemas
Outline Authentication & Authorization: OAuth 2.0, Azure AD, tenant context, RBAC
Specify Error Handling: Standard error responses, status codes, error details
Document Pagination & Filtering: Cursor-based pagination, filter syntax, sorting
Detail Rate Limiting: Per-tenant quotas, throttling, 429 responses, Retry-After
Describe Validation: Request validation, schema validation, business rule validation
Outline API Versioning: URI versioning, deprecation, migration strategies
Document API Testing: Contract tests, integration tests, load tests
Specify API Observability: Distributed tracing, metrics, logging, monitoring

Out of scope (referenced elsewhere)

Message schemas and async contracts (see message-schemas.md)
Webhook specifications (see webhooks.md)
Idempotency patterns (see shared/idempotency.md)
Domain model details (see ../aggregates-entities.md)
Implementation patterns (see ../../implementation/)
SDK usage guides (see ../../sdk/)

Readers & ownership

Backend Developers (owners): API implementation, endpoint design, validation logic
Frontend Developers: API consumption, error handling, SDK usage
Integration Engineers: External system integration, API client development
QA/Test Engineers: API testing, contract validation, load testing
Security Engineers: Authentication, authorization, input validation, rate limiting
Operations/SRE: API monitoring, performance tuning, incident response
Partner Engineers: Third-party integration, API key management

Artifacts produced

OpenAPI 3.0 Specification: Complete machine-readable API definition
Endpoint Catalog: All endpoints organized by API and resource
Request/Response Schemas: JSON Schema definitions for all payloads
Authentication Guide: OAuth 2.0 flows, token management, tenant context
Error Response Catalog: All error codes with descriptions and examples
Rate Limiting Specification: Quota definitions, headers, 429 handling
Pagination Guide: Cursor-based pagination, sorting, filtering
API Client Examples: cURL, C#, JavaScript, Python samples
Postman Collection: Importable collection for all endpoints
API Testing Suite: Contract tests, integration tests, load tests
API Monitoring Dashboards: Metrics, latency, error rates, quotas
API Documentation Portal: Interactive API docs (Swagger UI, ReDoc)

Acceptance (done when)

All API endpoints are documented with complete OpenAPI 3.0 specifications
Request/response schemas are defined with JSON Schema validation rules
Authentication flows are documented with examples (OAuth 2.0, API keys)
Error responses follow standard format with all status codes documented
Rate limiting is specified with quotas, headers, and throttling behavior
Pagination is consistent across all list endpoints with cursor-based approach
Filtering and sorting syntax is documented with examples
API versioning strategy is documented with migration guides
Code examples are provided for all endpoints in multiple languages
Postman collection is available and up-to-date
Contract tests validate all endpoints in CI/CD
API monitoring is operational with dashboards and alerts
Documentation complete with interactive portal, examples, and troubleshooting

Detailed Cycle Plan¶

CYCLE 1: OpenAPI Fundamentals & API Architecture (~2,500 lines)¶

Topic 1: OpenAPI and REST API Principles¶

What will be covered:

What is OpenAPI?
OpenAPI Specification (OAS) 3.0 overview
OpenAPI vs Swagger (history and evolution)
OpenAPI structure (info, servers, paths, components, security)
OpenAPI benefits (documentation, code generation, validation, testing)
OpenAPI tooling (Swagger UI, ReDoc, Postman, code generators)
Why OpenAPI for ATP?
Machine-readable API contracts
Auto-generated documentation (Swagger UI)
Client SDK generation (C#, JavaScript, Python)
Contract-first development
API validation and testing
Developer portal integration
RESTful API Principles
REST Architecture: Representational State Transfer
Resource-Oriented: URLs represent resources, not actions
HTTP Verbs: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)
Stateless: No server-side session state
Cacheable: Response caching with headers
Layered System: Client doesn't know about intermediaries
Uniform Interface: Standard HTTP methods and status codes
ATP REST API Design Philosophy
Resource-Centric: /audit-events, /event-streams, /policies, /exports
Versioned: /api/v1/, /api/v2/ for backward compatibility
Tenant-Scoped: X-Tenant-Id header on all requests
Idempotent Writes: Idempotency-Key header for POST/PUT
Consistent Errors: Standard error format across all endpoints
Rate Limited: Per-tenant quotas with 429 responses
Well-Documented: OpenAPI specs with examples and descriptions
HTTP Status Codes in ATP
2xx Success:
- 200 OK: Successful GET request
- 201 Created: Successful POST creating resource
- 202 Accepted: Async operation started (exports)
- 204 No Content: Successful DELETE
3xx Redirection:
- 304 Not Modified: Resource unchanged (ETag)
4xx Client Errors:
- 400 Bad Request: Invalid request syntax or validation
- 401 Unauthorized: Missing or invalid authentication
- 403 Forbidden: Authenticated but not authorized
- 404 Not Found: Resource doesn't exist
- 409 Conflict: Duplicate or conflicting resource
- 422 Unprocessable Entity: Validation failed
- 429 Too Many Requests: Rate limit exceeded
5xx Server Errors:
- 500 Internal Server Error: Unexpected error
- 503 Service Unavailable: Service down or overloaded
- 504 Gateway Timeout: Upstream timeout

OpenAPI Specification Structure

openapi: 3.0.3
info:
  title: Audit Trail Platform REST APIs
  version: 1.0.0
  description: |
    ATP REST APIs for ingesting, querying, and managing audit events.
  contact:
    name: ATP Platform Team
    email: atp-support@connectsoft.example
  license:
    name: Proprietary

servers:
  - url: https://api.atp.connectsoft.example/api/v1
    description: Production
  - url: https://api-staging.atp.connectsoft.example/api/v1
    description: Staging
  - url: https://api-dev.atp.connectsoft.example/api/v1
    description: Development

tags:
  - name: Ingestion
    description: Audit event ingestion endpoints
  - name: Query
    description: Audit event query and search endpoints
  - name: Policy
    description: Policy management endpoints
  - name: Export
    description: Export and eDiscovery endpoints

paths:
  /audit-events:
    post: ...
    get: ...

components:
  schemas: ...
  securitySchemes: ...
  parameters: ...
  responses: ...

Code Examples: - Complete OpenAPI specification header - Path definition example - Component schema example - Security scheme definition

Diagrams: - OpenAPI structure overview - REST API architecture - HTTP status code decision tree - API versioning strategy

Deliverables: - OpenAPI fundamentals guide - REST principles for ATP - Specification template - Status code reference

Topic 2: ATP REST API Architecture¶

What will be covered:

API Gateway Pattern
Single entry point (Audit.Gateway)
Routing to backend services
Cross-cutting concerns (auth, logging, rate limiting)
TLS termination

ATP API Topology

Azure Front Door (WAF)
  ↓
API Gateway (Audit.Gateway)
  ├── Ingestion API → Ingestion Service
  ├── Query API → Query Service
  ├── Policy API → Policy Service
  ├── Export API → Export Service
  └── Admin API → Admin Service

API Versioning Strategy
URI Versioning: /api/v1/, /api/v2/ (ATP approach)
Version in path (clear, cache-friendly)
Major version only in URI (v1, v2, not v1.2)
Minor/patch changes backward compatible
Deprecation and sunset policies

Base URL Structure

https://{environment}.atp.connectsoft.example/api/{version}/{resource}

Examples:
- https://api.atp.connectsoft.example/api/v1/audit-events
- https://api-staging.atp.connectsoft.example/api/v1/policies
- https://api-dev.atp.connectsoft.example/api/v1/exports

Resource Naming Conventions
Plural nouns: /audit-events, /policies, /exports
Lowercase with hyphens: /event-streams, /export-requests
Hierarchical: /event-streams/{streamId}/events
Query parameters for filtering: ?tenantId=...&status=...
API Categories
Ingestion API: Write operations (ingest events)
Query API: Read operations (search, filter, retrieve)
Policy API: Policy CRUD (classification, retention)
Export API: Long-running export operations
Admin API: Operational endpoints (health, metrics, control)
Cross-Cutting Concerns
Authentication: OAuth 2.0 Bearer tokens
Authorization: RBAC with tenant scoping
Correlation: X-Correlation-Id header propagation
Idempotency: Idempotency-Key header for writes
Tenant Context: X-Tenant-Id header (required)
Rate Limiting: Per-tenant quotas
Compression: gzip, br support
Caching: ETag, Cache-Control headers
API Gateway Responsibilities
TLS termination
Authentication validation
Tenant resolution
Rate limiting enforcement
Request validation (schema)
Routing to backend services
Response transformation
Error handling standardization
Observability (logging, tracing, metrics)

Code Examples: - OpenAPI server definitions - Base URL examples - Resource naming examples - Gateway routing configuration

Diagrams: - API gateway architecture - Request flow through gateway - API versioning strategy - Resource hierarchy

Deliverables: - API architecture specification - Gateway configuration guide - Versioning strategy - Naming conventions

CYCLE 2: Ingestion API Specifications (~3,000 lines)¶

Topic 3: Single Event Ingestion Endpoint¶

What will be covered:

POST /api/v1/audit-events

Complete OpenAPI Specification:

href="#__codelineno-3-1">/audit-events: post: operationId: ingestAuditEvent summary: Ingest single audit event description: | Ingests a single audit event into ATP. The event is validated, classified, and stored immutably. Returns immediately with event ID; processing is asynchronous. Supports idempotency via Idempotency-Key header to prevent duplicates. tags: - Ingestion security: - BearerAuth: [] parameters: - $ref: '#/components/parameters/TenantIdHeader' - $ref: '#/components/parameters/CorrelationIdHeader' - $ref: '#/components/parameters/IdempotencyKeyHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IngestAuditEventRequest' examples: userLogin: summary: User login event value: timestamp: "2024-10-30T10:30:00.123Z" actor: userId: "user-123" userName: "alice@example.com" actorType: "User" action: "User.Login" resource: resourceType: "Application" resourceId: "app-portal" resourceName: "Customer Portal" context: ipAddress: "192.168.1.100" userAgent: "Mozilla/5.0..." sessionId: "sess-xyz-789" payload: loginMethod: "Password" mfaEnabled: true responses: '201': description: Event ingested successfully headers: X-Event-Id: schema: type: string description: Unique event identifier (ULID) X-Correlation-Id: schema: type: string description: Request correlation ID Location: schema: type: string description: URI to retrieve the event example: /api/v1/audit-events/01HQZXYZ123 content: application/json: schema: $ref: '#/components/schemas/IngestAuditEventResponse' example: eventId: "01HQZXYZ123456789ABCDEF" tenantId: "tenant-abc-123" status: "Accepted" timestamp: "2024-10-30T10:30:00.123Z" message: "Audit event ingested successfully" idempotent: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError'

Request Schema Details

components:
  schemas:
    IngestAuditEventRequest:
      type: object
      required:
        - timestamp
        - actor
        - action
        - resource
      properties:
        timestamp:
          type: string
          format: date-time
          description: When the action occurred (UTC, ISO 8601)
          example: "2024-10-30T10:30:00.123Z"
        actor:
          $ref: '#/components/schemas/Actor'
        action:
          type: string
          description: Action performed (Verb.Noun format)
          pattern: "^[A-Za-z]+\\.[A-Za-z]+$"
          minLength: 3
          maxLength: 100
          example: "User.Login"
        resource:
          $ref: '#/components/schemas/Resource'
        context:
          type: object
          description: Additional contextual information
          additionalProperties: true
          example:
            ipAddress: "192.168.1.100"
            userAgent: "Mozilla/5.0..."
        payload:
          type: object
          description: Event-specific data (encrypted if sensitive)
          additionalProperties: true
        correlationId:
          type: string
          format: uuid
          description: Optional correlation ID (generated if not provided)

    Actor:
      type: object
      required:
        - actorType
      properties:
        userId:
          type: string
          description: User identifier (if actor is user)
        userName:
          type: string
          format: email
          description: User email or username
        serviceId:
          type: string
          description: Service identifier (if actor is service)
        serviceName:
          type: string
          description: Service name
        actorType:
          type: string
          enum: [User, Service, System]
          description: Type of actor

    Resource:
      type: object
      required:
        - resourceType
        - resourceId
      properties:
        resourceType:
          type: string
          description: Type of resource affected
          example: "Document"
        resourceId:
          type: string
          description: Unique identifier of resource
          example: "doc-123"
        resourceName:
          type: string
          description: Human-readable resource name
          example: "Q3 Financial Report"

Response Schema Details
Success response (201 Created)
Response headers (X-Event-Id, Location)
Idempotent response (200 OK if duplicate)
Error responses (all 4xx and 5xx)
Authentication Requirements
Bearer token required (OAuth 2.0)
Token must have audit:write scope
Tenant context from token claims or header
Authorization Rules
User must have write permission in tenant
Service accounts require audit.events.write permission
Cross-tenant writes forbidden
Validation Rules
Timestamp not in future (tolerance: 5 minutes)
Action format: Verb.Noun (e.g., User.Login, Document.Delete)
Actor must be specified (user, service, or system)
Resource must exist in tenant (optional validation)
Payload size limit: 64KB
Idempotency Behavior
Idempotency-Key header required for duplicate prevention
Duplicate detection window: 24 hours
Duplicate response: 200 OK with idempotent: true
Idempotency key format: UUID or ULID
Rate Limiting
Default: 1,000 requests/minute per tenant
Premium: 10,000 requests/minute
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
429 response with Retry-After header

Code Examples: - Complete OpenAPI path definition - Complete request/response schemas - cURL example - C# HttpClient example - JavaScript fetch example - Idempotency example - Rate limit handling

Diagrams: - Ingestion endpoint flow - Authentication flow - Validation pipeline - Idempotency check flow - Rate limiting mechanism

Deliverables: - Complete OpenAPI spec for POST /audit-events - Request/response JSON Schemas - Client code examples (3 languages) - Validation rules documentation - Idempotency guide

Topic 4: Batch Ingestion Endpoint¶

What will be covered:

POST /api/v1/audit-events/batch

Complete OpenAPI Specification: - Batch ingestion for high-volume scenarios - Request: Array of audit events (up to 1,000 per batch) - Response: Batch ID, success/failure counts, individual event results - Partial success handling (some events succeed, others fail) - Transaction semantics (all-or-nothing vs best-effort)

Batch Request Schema

BatchIngestRequest:
  type: object
  required:
    - events
  properties:
    events:
      type: array
      items:
        $ref: '#/components/schemas/IngestAuditEventRequest'
      minItems: 1
      maxItems: 1000
      description: Array of audit events to ingest
    transactional:
      type: boolean
      default: false
      description: If true, all events must succeed or all fail

Batch Response Schema
Batch ID for tracking
Overall status (Completed, PartialSuccess, Failed)
Success count and failure count
Per-event results (eventId or error)
Batch Processing Behavior
Validation: All events validated before processing
Transactional mode: Atomic (all or nothing)
Best-effort mode: Process each independently
Partial failures: Return 207 Multi-Status
Batch Size Limits
Maximum: 1,000 events per batch
Recommended: 100-500 for best performance
Request size limit: 10MB
Processing timeout: 60 seconds
Batch Idempotency
Idempotency-Key for entire batch
Per-event duplicate detection (by eventId)
Idempotent batch replay

Code Examples: - Complete OpenAPI spec for batch endpoint - Batch request/response schemas - Batch processing examples (C#) - Partial failure handling - Batch idempotency implementation

Diagrams: - Batch processing flow - Transactional vs best-effort - Partial failure handling - Batch size optimization

Deliverables: - Complete OpenAPI spec for batch ingestion - Batch processing guide - Client implementation examples - Performance optimization tips

CYCLE 3: Query API Specifications (~3,500 lines)¶

Topic 5: Event Retrieval Endpoints¶

What will be covered:

GET /api/v1/audit-events
List audit events with filtering, pagination, sorting
Complete OpenAPI specification
Query parameters: tenantId, actorId, action, resourceId, startTime, endTime
Pagination: cursor-based (efficient for large datasets)
Sorting: by timestamp, eventId, action
Response: Array of events with pagination metadata
GET /api/v1/audit-events/{eventId}
Retrieve single event by ID
Complete OpenAPI specification
Path parameter: eventId (ULID)
Response: Complete event details
404 if not found or not authorized
GET /api/v1/event-streams/{streamId}
Retrieve event stream metadata
Complete OpenAPI specification
Response: Stream info, event count, status, hash chain
GET /api/v1/event-streams/{streamId}/events
List events in specific stream
Pagination support
Ordered by sequence number

Complete OpenAPI specifications for all query endpoints

Deliverables: - OpenAPI specs for 4 query endpoints - Request/response schemas - Query parameter documentation - Pagination guide

Topic 6: Advanced Search Endpoint¶

What will be covered:

POST /api/v1/audit-events/search

Complete OpenAPI Specification: - Advanced search with complex filters - Request body: Search criteria (JSON) - Full-text search support - Date range queries - Multi-field filtering - Aggregations and facets - Response: Results with metadata

Search Request Schema

SearchAuditEventsRequest:
  type: object
  properties:
    query:
      type: string
      description: Full-text search query
      example: "login failed"
    filters:
      type: object
      properties:
        actorIds:
          type: array
          items:
            type: string
        actions:
          type: array
          items:
            type: string
        resourceTypes:
          type: array
          items:
            type: string
        timeRange:
          type: object
          properties:
            from:
              type: string
              format: date-time
            to:
              type: string
              format: date-time
        classifications:
          type: array
          items:
            type: string
            enum: [Public, Internal, Confidential, Secret]
    sort:
      type: array
      items:
        type: object
        properties:
          field:
            type: string
          order:
            type: string
            enum: [asc, desc]
    pagination:
      type: object
      properties:
        cursor:
          type: string
        limit:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
    aggregations:
      type: array
      items:
        type: string
        enum: [byAction, byActor, byResource, byClassification]

Search Response Schema
Results array
Total count (approximate)
Next cursor for pagination
Aggregation results
Search metadata (query time, index version)
Search Capabilities
Full-text search (indexed fields)
Exact match filtering
Range queries (timestamp)
Boolean logic (AND, OR, NOT)
Wildcard and fuzzy matching
Search Performance
Index-backed queries
Query timeout: 30 seconds
Result limits: max 10,000 results
Pagination required for large datasets

Code Examples: - Complete OpenAPI spec for search - Search request/response schemas - Search query examples (simple, complex) - Aggregation examples - Client code (C#, JavaScript)

Diagrams: - Search architecture - Query execution flow - Index structure - Aggregation pipeline

Deliverables: - Complete search API specification - Search syntax guide - Performance optimization tips - Example queries library

CYCLE 4: Policy API Specifications (~2,500 lines)¶

Topic 7: Policy CRUD Operations¶

What will be covered:

POST /api/v1/policies
Create new policy
Request: Policy configuration (classification, retention, access rules)
Response: Created policy with ID
GET /api/v1/policies
List policies for tenant
Query parameters: policyType, status, active
Pagination support
GET /api/v1/policies/{policyId}
Retrieve single policy
Response: Complete policy details
PUT /api/v1/policies/{policyId}
Update existing policy
Request: Updated policy configuration
Versioning: Optimistic concurrency with If-Match header
DELETE /api/v1/policies/{policyId}
Delete policy (soft delete)
Validation: Cannot delete if in use
Response: 204 No Content

Complete OpenAPI specifications for all policy endpoints

Deliverables: - OpenAPI specs for 5 policy endpoints - Policy schema definitions - CRUD examples

Topic 8: Policy Rules and Configuration¶

What will be covered:

POST /api/v1/policies/{policyId}/rules
Add rule to policy
DELETE /api/v1/policies/{policyId}/rules/{ruleId}
Remove rule from policy
GET /api/v1/policies/templates
Get policy templates
POST /api/v1/policies/validate
Validate policy configuration before creating

Complete specifications

CYCLE 5: Export API Specifications (~2,500 lines)¶

Topic 9: Export Request and Status¶

What will be covered:

POST /api/v1/exports
Request export of audit events
Request: Search criteria, format, destination
Response: Export request ID (202 Accepted)
Async operation (long-running)
GET /api/v1/exports/{exportId}
Get export status
Response: Status (Pending, Processing, Completed, Failed), progress
GET /api/v1/exports
List export requests
Query parameters: status, tenantId, createdAfter
Pagination support

Complete OpenAPI specifications

Topic 10: Export Download and Delivery¶

What will be covered:

GET /api/v1/exports/{exportId}/download
Download completed export
Response: Binary file (ZIP, CSV, JSON)
Streaming for large exports
Signed URL (time-limited access)
POST /api/v1/exports/{exportId}/deliver
Deliver export to external destination
Request: Delivery configuration (SFTP, S3, etc.)
Response: Delivery status
DELETE /api/v1/exports/{exportId}
Cancel pending export or delete completed export
Response: 204 No Content

Complete specifications

CYCLE 6: Admin & Control Plane APIs (~2,000 lines)¶

Topic 11: Health and Status Endpoints¶

What will be covered:

GET /api/v1/health
Overall health status
Response: Status (Healthy, Degraded, Unhealthy)
GET /api/v1/health/live
Liveness probe (for Kubernetes)
GET /api/v1/health/ready
Readiness probe (for Kubernetes)
GET /api/v1/status
Detailed system status
Component health, metrics, version

Complete specifications

Topic 12: Admin Operations¶

What will be covered:

POST /api/v1/admin/projections/rebuild
Rebuild read model projections
GET /api/v1/admin/dead-letter-queue
List messages in DLQ
POST /api/v1/admin/dead-letter-queue/{messageId}/reprocess
Reprocess DLQ message
GET /api/v1/admin/metrics
System metrics and KPIs

Complete specifications

CYCLE 7: Authentication & Authorization (~2,500 lines)¶

Topic 13: Authentication Mechanisms¶

What will be covered:

OAuth 2.0 Bearer Tokens
Azure AD integration
Token acquisition flows
Token validation
Scope requirements
API Keys (Service-to-Service)
API key generation
API key rotation
API key in header (X-API-Key)
Tenant Context Resolution
X-Tenant-Id header (explicit)
Tenant from token claims (implicit)
Multi-tenant token handling

Complete authentication documentation

Topic 14: Authorization and RBAC¶

What will be covered:

Role-Based Access Control (RBAC)
Roles: Admin, Operator, Auditor, Viewer
Permissions per role
Scope per API endpoint
Tenant-Scoped Authorization
Cross-tenant access denied
Tenant admin privileges
Tenant user permissions
Resource-Level Authorization
Event-level access control
Classification-based filtering
Data redaction for unauthorized users

Complete authorization documentation

CYCLE 8: Error Handling & Validation (~2,000 lines)¶

Topic 15: Standard Error Responses¶

What will be covered:

Error Response Format

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [
      {
        "field": "timestamp",
        "issue": "Timestamp cannot be in the future",
        "value": "2025-01-01T00:00:00Z"
      }
    ],
    "traceId": "00-abc123...",
    "timestamp": "2024-10-30T10:30:00Z",
    "path": "/api/v1/audit-events",
    "requestId": "req-xyz-789"
  }
}

Error Code Catalog
All error codes documented
Error scenarios and resolution
Examples for each error

Complete error handling specifications

Topic 16: Request Validation¶

What will be covered:

Schema Validation
JSON Schema validation
Required fields enforcement
Data type validation
Format validation
Business Rule Validation
Timestamp rules
Action format rules
Resource existence
Policy compliance
Validation Error Responses
422 Unprocessable Entity
Detailed field-level errors
Validation error examples

Complete validation documentation

CYCLE 9: Pagination, Filtering & Performance (~2,500 lines)¶

Topic 17: Pagination Strategies¶

What will be covered:

Cursor-Based Pagination
Why cursor-based (consistent, efficient)
Cursor format (opaque token)
Next/previous cursors
Limit parameter
Pagination Response
Data array
Pagination metadata (total, cursor, hasMore)
Navigation links (next, previous)
Pagination Best Practices
Default limit: 100
Maximum limit: 1,000
Cursor expiration: 24 hours

Complete pagination documentation

Topic 18: Filtering and Sorting¶

What will be covered:

Filter Syntax
Query parameters
Filter operators (eq, ne, gt, lt, in, contains)
Combining filters (AND logic)
Sort Syntax
Sort parameter
Multiple sort fields
Ascending/descending
Performance Optimization
Indexed fields for filtering
Query optimization tips
Avoid N+1 queries

Complete filtering documentation

CYCLE 10: Versioning, Testing & Observability (~2,500 lines)¶

Topic 19: API Versioning and Deprecation¶

What will be covered:

URI Versioning Strategy
/api/v1/, /api/v2/
Version lifecycle
Migration guides
Deprecation Process
Deprecation headers
Sunset dates
Migration timeline
Version Compatibility
Breaking vs non-breaking changes
Compatibility matrix

Complete versioning documentation

Topic 20: API Testing and Observability¶

What will be covered:

Contract Testing
OpenAPI validation tests
Request/response validation
Contract test automation
Integration Testing
End-to-end API tests
Multi-step scenarios
Test data management
Load Testing
Performance benchmarks
Throughput testing
Latency testing
API Monitoring
Request metrics (rate, latency, errors)
Distributed tracing
Logging and debugging
Dashboards and alerts

Complete testing and observability documentation

API Quick Reference¶

All ATP REST API Endpoints¶

Ingestion API (2 endpoints): - POST /api/v1/audit-events - Ingest single event - POST /api/v1/audit-events/batch - Batch ingestion

Query API (4 endpoints): - GET /api/v1/audit-events - List events - GET /api/v1/audit-events/{id} - Get event - POST /api/v1/audit-events/search - Advanced search - GET /api/v1/event-streams/{id} - Get stream

Policy API (5 endpoints): - POST /api/v1/policies - Create policy - GET /api/v1/policies - List policies - GET /api/v1/policies/{id} - Get policy - PUT /api/v1/policies/{id} - Update policy - DELETE /api/v1/policies/{id} - Delete policy

Export API (4 endpoints): - POST /api/v1/exports - Request export - GET /api/v1/exports - List exports - GET /api/v1/exports/{id} - Get export status - GET /api/v1/exports/{id}/download - Download export

Admin API (5 endpoints): - GET /api/v1/health - Health check - GET /api/v1/status - System status - POST /api/v1/admin/projections/rebuild - Rebuild projections - GET /api/v1/admin/dead-letter-queue - List DLQ - GET /api/v1/admin/metrics - System metrics

Total: 20 endpoints

Summary & Implementation Plan¶

Implementation Phases¶

Phase 1: Foundations (Cycles 1-2) - 2 weeks - OpenAPI fundamentals and ingestion API

Phase 2: Query (Cycle 3) - 2 weeks - Query and search APIs

Phase 3: Management (Cycles 4-5) - 2 weeks - Policy and export APIs

Phase 4: Operations (Cycle 6) - 1 week - Admin and health APIs

Phase 5: Cross-Cutting (Cycles 7-9) - 3 weeks - Auth, errors, pagination, filtering

Phase 6: Quality (Cycle 10) - 1 week - Versioning, testing, observability

Success Metrics¶

API Coverage: 20 endpoints fully documented
OpenAPI Valid: Passes OpenAPI 3.0 validation
Code Generation: SDKs generated from OpenAPI
Contract Tests: 100% endpoints have tests
Response Time: P95 < 200ms for queries
Availability: 99.9% uptime SLA

Document Status: ✅ Plan Approved - Ready for Content Generation

Target Start Date: Q2 2025

Expected Completion: Q3 2025 (11 weeks)

Owner: API Engineering Team

Last Updated: 2024-10-30