API Specifications

API Specifications

TMI provides comprehensive API specifications in multiple formats to support integration with various tools and clients.

OpenAPI 3.0 Specification

The primary REST API is fully documented using OpenAPI 3.0.3.

Source Specification

• File: tmi-openapi.json (v1.0.0)
• Location: tmi/docs/reference/apis/tmi-openapi.json
• Format: JSON with $ref references
• Includes: Complete request/response schemas, authentication, and examples

Processed Specifications

For tools that don't support $ref resolution, use resolved specifications with all references inlined:

• Resolved JSON - Self-contained JSON
• Resolved YAML - Self-contained YAML
• Unresolved JSON - Modular with $ref pointers
• Unresolved YAML - Modular with $ref pointers

REST API Endpoints

The OpenAPI specification documents all REST endpoints including:

• Threat Models - Create, read, update, delete threat models
• Diagrams - Manage data flow diagrams
• Threats - Identify and track threats
• Users - User management and authentication
• Authorization - Role-based access control

For detailed endpoint documentation:

1. View the HTML documentation
2. Open tmi-openapi.json in Swagger Editor
3. Use the generated client SDKs below

AsyncAPI Specification

The WebSocket collaboration protocol is documented using AsyncAPI.

• File: tmi-asyncapi.yml
• Location: tmi/docs/reference/apis/tmi-asyncapi.yml
• Describes: Real-time diagram updates and collaborative editing via WebSocket

API Workflows

Pre-defined workflow patterns for common integration scenarios.

• File: api-workflows.json
• Location: tmi/docs/reference/apis/api-workflows.json
• Includes: Workflows for threat model creation, diagram editing, threat identification, and more

Arazzo Workflow Specifications

TMI provides Arazzo v1.0.1 workflow specifications that document API workflow sequences:

• tmi.arazzo.yaml - Human-readable YAML format
• tmi.arazzo.json - Machine-readable JSON format

Features:

• Generated from OpenAPI + workflow knowledge base
• PKCE OAuth flow with code_verifier and code_challenge
• 7 complete end-to-end workflows
• Prerequisite mapping via dependsOn relationships

Location: tmi/docs/reference/apis/

For generation details, see arazzo-generation.md

Arazzo Validation and Maintenance

The Arazzo specifications are validated using make validate-arazzo. Key validation requirements:

ID Pattern Requirements (per Arazzo v1.0.1 spec):

• workflowId and stepId must match pattern [A-Za-z0-9_-]+
• IDs are case-sensitive and must be unique within their scope

Runtime Expression Syntax:

• Use $steps.stepId.outputs.field format (no curly braces)
• Example: $steps.oauth_token_exchange.outputs.access_token

operationPath vs operationId:

• Both are valid per spec; TMI uses operationPath for simplicity
• When using operationPath, don't duplicate inline parameters or requestBody

Enhancement Script (enhance-arazzo-with-workflows.py):

• _sanitize_id() - Cleans IDs to match required pattern
• _sanitize_scaffold() - Auto-generates missing descriptions
• _add_workflow_outputs() - Adds workflow-level outputs for OAuth and CRUD workflows

Current Validation Status:

• Errors: 0
• Warnings: 132 (expected - operationId preference hints)

For complete validation fix history, see the validation change log in the repository

Generated Client SDKs

Auto-generated client libraries for multiple programming languages (from OpenAPI spec):

• Go SDK - Go client library
• Java SDK - Java client with Maven support
• JavaScript SDK - JavaScript/Node.js client
• Python SDK - Python client with pip

Each SDK includes type-safe models, OAuth 2.0 authentication helpers, and usage examples.

Authentication

All API endpoints require OAuth 2.0 authentication with JWT tokens.

See Setting-Up-Authentication and the Authorization Reference for details on:

• OAuth flow and token acquisition
• Role-based access control (owner, writer, reader)
• Permission resolution logic
• Pseudo-groups (e.g., "everyone")

Rate Limiting

TMI implements a comprehensive tiered rate limiting strategy with four tiers:

1. Public Discovery - IP-based limits for metadata endpoints
2. Auth Flows - Multi-scope limits (session, IP, user identifier) for OAuth/SAML
3. Resource Operations - User-based configurable limits for API endpoints
4. Webhooks - Database-backed quotas for webhook subscriptions

The OpenAPI specification includes x-rate-limit extensions documenting rate limits for all endpoints. See API-Rate-Limiting for:

• Detailed tier definitions and limits
• Multi-scope enforcement mechanisms
• Client integration best practices with code examples
• Database schema for configurable quotas
• Implementation roadmap and status

API Integration Guides

For practical guidance on using the APIs:

• API-Integration - Getting started with the API
• Client Integration Guide - Detailed integration patterns
• WebSocket Testing - Real-time collaboration testing

Using the Specifications

For API Consumers

1. Quick Reference: View the interactive HTML documentation
2. Client Development: Use the appropriate SDK for your language
3. Tool Integration: Import resolved specifications into tools like Postman, Insomnia, or API management platforms
4. Validation: Validate requests/responses against the source specification

For API Developers

1. Source of Truth: Edit tmi-openapi.json - never modify generated artifacts
2. Validation: Run make validate-openapi before committing changes
3. Regeneration: After updates, regenerate specs via SwaggerHub
4. Version Control: Commit both source and generated artifacts to track evolution

Versioning

The current API version is 1.0.0. Breaking changes will increment the major version number.

Related Documentation

• API-Workflows - Pre-built workflow patterns
• Configuration-Reference - API configuration options
• Security-Best-Practices - API security guidance
• Testing Guide