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

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