${contract.info.title}

# Integration Contracts > **Skill Purpose:** API contract definition, interface standardization, and cross-system integration patterns --- ## Core Skill Pattern **Objective:** Establish comprehensive API contract patterns with standardized interfaces, request/response schemas, and integration documentation. **Universal Pattern:** 1. Define API contract standards and specifications 2. Create request/response schema patterns 3. Set up interface documentation and generation 4. Establish contract testing and validation 5. Create versioning and evolution procedures **Key Decisions (Project-Specific):** - API specification format and documentation approach - Schema validation and type generation methods - Contract testing and validation requirements - Versioning strategy and backward compatibility - Integration documentation depth and format --- ## Project-Specific Implementation Notes **Customize per project:** - API specification format based on team preferences and tooling - Schema validation depth based on data criticality - Documentation detail based on stakeholder needs - Versioning strategy based on API stability requirements - Testing coverage based on integration complexity --- ## Example Implementation (OpenAPI Contract Pattern) > **Note:** This is an example pattern using OpenAPI specifications. Adapt contract format and documentation based on your specific project requirements and API architecture. ### Prerequisites (Example) - API endpoints designed and specified - Request/response schemas defined - Integration requirements documented --- ## Example: Integration Contracts Implementation > **Framework-Specific Example:** This demonstrates OpenAPI contract patterns. Adapt for your API specification and documentation requirements. ### 1. Contract Specification Definition ```typescript // OpenAPI specification structure interface OpenAPISpec { openapi: string; info: APIInfo; servers: ServerInfo[]; paths: PathItems; components: Components; security?: SecurityRequirements[]; } interface APIInfo { title: string; description: string; version: string; contact?: ContactInfo; license?: LicenseInfo; } interface PathItems { [path: string]: PathItem; } interface PathItem { get?: Operation; post?: Operation; put?: Operation; delete?: Operation; patch?: Operation; } interface Operation { operationId: string; summary: string; description?: string; tags?: string[]; parameters?: Parameter[]; requestBody?: RequestBody; responses: Responses; security?: SecurityRequirements[]; } // Example contract specification const apiContract: OpenAPISpec = { openapi: '3.0.0', info: { title: 'Project API', description: 'API specification for Project', version: '1.0.0' }, servers: [ { url: 'https://api.example.com/v1', description: 'Production server' }, { url: 'http://localhost:3000/api', description: 'Development server' } ], paths: { '/users': { get: { operationId: 'getUsers', summary: 'Get all users', tags: ['users'], parameters: [ { name: 'page', in: 'query', schema: { type: 'integer', default: 1 } }, { name: 'limit', in: 'query', schema: { type: 'integer', default: 10 } } ], responses: { 200: { description: 'List of users', content: { 'application/json': { schema: { type: 'object', properties: { users: { type: 'array', items: { $ref: '#/components/schemas/User' } }, pagination: { $ref: '#/components/schemas/Pagination' } } } } } } } }, post: { operationId: 'createUser', summary: 'Create a new user', tags: ['users'], requestBody: { required: true, content: { 'application/json': { schema: { $ref: '#/components/schemas/CreateUserRequest' } } } }, responses: { 201: { description: 'User created successfully', content: { 'application/json': { schema: { $ref: '#/components/schemas/User' } } } } } } } }, components: { schemas: { User: { type: 'object', properties: { id: { type: 'string', format: 'uuid' }, email: { type: 'string', format: 'email' }, name: { type: 'string' }, createdAt: { type: 'string', format: 'date-time' }, updatedAt: { type: 'string', format: 'date-time' } }, required: ['id', 'email', 'name'] }, CreateUserRequest: { type: 'object', properties: { email: { type: 'string', format: 'email' }, name: { type: 'string' }, password: { type: 'string', minLength: 8 } }, required: ['email', 'name', 'password'] }, Pagination: { type: 'object', properties: { page: { type: 'integer' }, limit: { type: 'integer' }, total: { type: 'integer' }, totalPages: { type: 'integer' } } } } } }; ``` ### 2. Schema Definition Patterns ```typescript // Schema definition and validation interface SchemaDefinition { name: string; type: 'object' | 'array' | 'string' | 'number' | 'boolean'; properties?: Record; items?: SchemaDefinition; required?: string[]; format?: string; pattern?: string; minimum?: number; maximum?: number; enum?: any[]; } // Schema validation patterns class SchemaValidator { private schemas = new Map(); registerSchema(name: string, schema: SchemaDefinition): void { this.schemas.set(name, schema); } validate(schemaName: string, data: any): ValidationResult { const schema = this.schemas.get(schemaName); if (!schema) { throw new Error(`Schema ${schemaName} not found`); } return this.validateAgainstSchema(data, schema); } private validateAgainstSchema(data: any, schema: SchemaDefinition): ValidationResult { const errors: ValidationError[] = []; // Type validation if (!this.validateType(data, schema.type)) { errors.push({ field: 'root', message: `Expected type ${schema.type}, got ${typeof data}` }); } // Required properties validation if (schema.type === 'object' && schema.required) { for (const requiredProp of schema.required) { if (!(requiredProp in data)) { errors.push({ field: requiredProp, message: 'Required property missing' }); } } } // Property validation if (schema.type === 'object' && schema.properties) { for (const [propName, propSchema] of Object.entries(schema.properties)) { if (propName in data) { const propResult = this.validateAgainstSchema(data[propName], propSchema); if (!propResult.valid) { errors.push(...propResult.errors.map(e => ({ ...e, field: `${propName}.${e.field}` }))); } } } } return { valid: errors.length === 0, errors }; } private validateType(data: any, expectedType: string): boolean { switch (expectedType) { case 'string': return typeof data === 'string'; case 'number': return typeof data === 'number'; case 'boolean': return typeof data === 'boolean'; case 'object': return typeof data === 'object' && data !== null && !Array.isArray(data); case 'array': return Array.isArray(data); default: return false; } } } interface ValidationResult { valid: boolean; errors: ValidationError[]; } interface ValidationError { field: string; message: string; } ``` ### 3. Contract Testing Patterns ```typescript // Contract testing framework interface ContractTest { name: string; endpoint: string; method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; request?: { headers?: Record; body?: any; query?: Record; }; expectedResponse: { status: number; headers?: Record; body?: any; schema?: string; }; } class ContractTester { private tests: ContractTest[] = []; addTest(test: ContractTest): void { this.tests.push(test); } async runTests(baseURL: string): Promise { const results: TestResult[] = []; for (const test of this.tests) { try { const result = await this.runSingleTest(test, baseURL); results.push(result); } catch (error) { results.push({ testName: test.name, passed: false, error: error instanceof Error ? error.message : 'Unknown error' }); } } return { totalTests: this.tests.length, passedTests: results.filter(r => r.passed).length, failedTests: results.filter(r => !r.passed).length, results }; } private async runSingleTest(test: ContractTest, baseURL: string): Promise { const url = `${baseURL}${test.endpoint}`; const options: RequestInit = { method: test.method, headers: { 'Content-Type': 'application/json', ...test.request?.headers } }; if (test.request?.body) { options.body = JSON.stringify(test.request.body); } // Add query parameters if (test.request?.query) { const params = new URLSearchParams(test.request.query); url += `?${params.toString()}`; } const response = await fetch(url, options); // Check status code if (response.status !== test.expectedResponse.status) { return { testName: test.name, passed: false, error: `Expected status ${test.expectedResponse.status}, got ${response.status}` }; } // Check response body if (test.expectedResponse.body) { const responseBody = await response.json(); if (!this.deepEqual(responseBody, test.expectedResponse.body)) { return { testName: test.name, passed: false, error: 'Response body does not match expected' }; } } // Check schema if (test.expectedResponse.schema) { const responseBody = await response.json(); const validation = schemaValidator.validate(test.expectedResponse.schema, responseBody); if (!validation.valid) { return { testName: test.name, passed: false, error: `Schema validation failed: ${validation.errors.map(e => e.message).join(', ')}` }; } } return { testName: test.name, passed: true }; } private deepEqual(obj1: any, obj2: any): boolean { return JSON.stringify(obj1) === JSON.stringify(obj2); } } interface TestResult { testName: string; passed: boolean; error?: string; } interface TestResults { totalTests: number; passedTests: number; failedTests: number; results: TestResult[]; } ``` ### 4. Contract Documentation Generation ```typescript // Documentation generation patterns interface DocumentationGenerator { generateFromContract(contract: OpenAPISpec): Documentation; generateMarkdown(contract: OpenAPISpec): string; generateHTML(contract: OpenAPISpec): string; } class OpenAPIDocumentationGenerator implements DocumentationGenerator { generateFromContract(contract: OpenAPISpec): Documentation { return { title: contract.info.title, description: contract.info.description, version: contract.info.version, endpoints: this.extractEndpoints(contract.paths), schemas: this.extractSchemas(contract.components?.schemas || {}), servers: contract.servers || [] }; } generateMarkdown(contract: OpenAPISpec): string { let markdown = `# ${contract.info.title}\n\n`; markdown += `${contract.info.description}\n\n`; markdown += `Version: ${contract.info.version}\n\n`; // Add endpoints markdown += '## Endpoints\n\n'; for (const [path, pathItem] of Object.entries(contract.paths)) { markdown += `### ${path}\n\n`; for (const [method, operation] of Object.entries(pathItem)) { if (operation && typeof operation === 'object' && 'summary' in operation) { markdown += `#### ${method.toUpperCase()} ${operation.summary}\n\n`; markdown += `${operation.description || ''}\n\n`; if (operation.parameters) { markdown += '**Parameters:**\n\n'; for (const param of operation.parameters) { markdown += `- \`${param.name}\` (${param.in}): ${param.description || ''}\n`; } markdown += '\n'; } } } } return markdown; } generateHTML(contract: OpenAPISpec): string { // Generate HTML documentation (could use Swagger UI or similar) return ` ${contract.info.title}

`; } private extractEndpoints(paths: PathItems): EndpointInfo[] { const endpoints: EndpointInfo[] = []; for (const [path, pathItem] of Object.entries(paths)) { for (const [method, operation] of Object.entries(pathItem)) { if (operation && typeof operation === 'object' && 'summary' in operation) { endpoints.push({ path, method: method.toUpperCase() as HTTPMethod, summary: operation.summary, description: operation.description, operationId: operation.operationId }); } } } return endpoints; } private extractSchemas(schemas: Record): SchemaInfo[] { return Object.entries(schemas).map(([name, schema]) => ({ name, type: schema.type, properties: schema.properties || {}, required: schema.required || [] })); } } interface Documentation { title: string; description: string; version: string; endpoints: EndpointInfo[]; schemas: SchemaInfo[]; servers: ServerInfo[]; } interface EndpointInfo { path: string; method: HTTPMethod; summary: string; description?: string; operationId: string; } interface SchemaInfo { name: string; type: string; properties: Record; required: string[]; } type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; ``` ### 5. Contract Versioning and Evolution ```typescript // Contract versioning patterns interface ContractVersion { version: string; spec: OpenAPISpec; changes: VersionChange[]; deprecated?: boolean; sunsetDate?: Date; } interface VersionChange { type: 'breaking' | 'feature' | 'fix'; description: string; affectedEndpoints: string[]; } class ContractVersionManager { private versions: ContractVersion[] = []; addVersion(version: ContractVersion): void { this.versions.push(version); } getLatestVersion(): ContractVersion | undefined { return this.versions .filter(v => !v.deprecated) .sort((a, b) => this.compareVersions(b.version, a.version))[0]; } getVersion(version: string): ContractVersion | undefined { return this.versions.find(v => v.version === version); } getBreakingChanges(fromVersion: string, toVersion: string): VersionChange[] { const from = this.getVersion(fromVersion); const to = this.getVersion(toVersion); if (!from || !to) return []; return to.changes.filter(change => change.type === 'breaking'); } private compareVersions(v1: string, v2: string): number { const parts1 = v1.split('.').map(Number); const parts2 = v2.split('.').map(Number); for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) { const part1 = parts1[i] || 0; const part2 = parts2[i] || 0; if (part1 > part2) return 1; if (part1 < part2) return -1; } return 0; } } ``` --- ## Integration Patterns ### API Department Integration - Contract definition and standardization - Schema validation and type generation - Documentation generation and maintenance ### UI Department Integration - Type-safe client generation - Request/response schema alignment - API documentation consumption ### Data Department Integration - Database schema alignment with API contracts - Data validation patterns - Schema trace integration --- ## Stop Conditions **STOP contract operations and escalate if:** - Contract specifications conflict with implementation - Schema validation fails consistently - Documentation generation fails - Version compatibility issues arise - Contract testing reveals major violations **PAUSE operations if:** - API specification under review - Schema changes in progress - Documentation updates pending - Version migration in progress --- ## Quality Standards **Contract Quality:** - Complete and accurate specifications - Consistent schema definitions - Clear documentation and examples - Comprehensive test coverage **Integration Quality:** - Type-safe client generation - Schema validation enforcement - Documentation accessibility - Version compatibility maintenance

Integration Contracts

Install this skill

Comments