api_contract #

A runtime API response contract validator for Flutter/Dart. Detect mismatches between your expected API contracts and actual server responses before they silently break your app.

🎯 The Problem #

Backend APIs change. Fields get renamed, types shift from int to String, optional fields become null, and new fields appear without warning. Your app keeps running — but with wrong data, broken UI, or silent failures.

api_contract catches these mismatches at runtime by validating API responses against a contract you define.

✨ Features #

• ✅ Runtime validation - Catch API contract violations before they cause bugs
• ✅ Multiple contract modes - Strict or lenient validation
• ✅ Type checking - Validate field types (string, number, boolean, list, map)
• ✅ Nested objects - Support for complex nested structures
• ✅ Built-in types - DateTime, Uri, Duration auto-detected
• ✅ Code generation - Auto-generate contracts from model classes
• ✅ Repository pattern - Clean integration with repository layer
• ✅ CI/CD friendly - Throw errors in CI, log warnings in development
• ✅ Zero runtime overhead in release - Disable validation in production

📦 Installation #

Add to your pubspec.yaml:

dependencies:
  api_contract: ^0.2.1

dev_dependencies:
  api_contract_generator: ^0.2.0
  build_runner: ^2.4.13

Then run:

dart pub get

🚀 Quick Start #

Option 1: Auto-Generate from Model (Recommended) #

1. Annotate your model:

import 'package:api_contract/api_contract.dart';
import 'package:api_contract_generator/api_contract_generator.dart';

part 'user.g.dart';

@ApiContractSchema(mode: ContractMode.strict, version: '1.0')
class User {
  User({
    required this.id,
    required this.name,
    required this.email,
    this.avatar,
    required this.createdAt,
  });

  final int id;
  final String name;
  final String email;

  @optional
  final String? avatar;  // Can be missing from response

  final DateTime createdAt;  // Auto-detected as string in JSON
}

2. Generate contract:

dart run build_runner build --delete-conflicting-outputs

3. Use in repository:

class UserRepo {
  Future<ApiResult<User>> getUser(int userId) async {
    try {
      final response = await _apiService.getUser(userId);

      // Validate response
      final validationResult = userContract.validate(response.toJson());
      validationResult.throwIfInvalid();

      return ApiResult.success(response);
    } catch (error) {
      return ApiResult.failure(error);
    }
  }
}

Option 2: Manual Contract Definition #

import 'package:api_contract/api_contract.dart';

final userContract = ApiContract(
  mode: ContractMode.strict,
  version: '1.0',
  fields: {
    'id':    ContractField.required(type: FieldType.number),
    'name':  ContractField.required(type: FieldType.string),
    'email': ContractField.required(type: FieldType.string),
    'avatar': ContractField.optional(type: FieldType.string),
    'createdAt': ContractField.required(type: FieldType.string),
  },
);

// Validate
final result = userContract.validate(responseJson);
result.throwIfInvalid();

📖 Usage Guide #

Contract Modes #

// Strict mode - flags unexpected fields as violations
@ApiContractSchema(mode: ContractMode.strict)

// Lenient mode - ignores extra fields (default)
@ApiContractSchema(mode: ContractMode.lenient)

Field Annotations #

class Post {
  final String title;        // Required by default

  @optional
  final String? description; // Can be missing from response

  @nullable
  final String? author;      // Must be present but can be null

  final DateTime createdAt;  // Auto-detected as string in JSON
}

Difference:

• @optional: Field can be missing from JSON → ContractField.optional()
• @nullable: Field must be present but value can be null → ContractField.nullable()

Supported Types #

Repository Pattern Integration #

class LessonRepo {
  final LessonApiService _apiService;

  Future<ApiResult<Lesson>> getLesson(int id) async {
    try {
      // 1. Fetch from API
      final response = await _apiService.getLesson(id);

      // 2. Validate contract
      final validationResult = lessonContract.validate(response.toJson());

      // 3. Handle violations
      validationResult.when(
        valid: () => print('✓ Valid response'),
        invalid: (violations) {
          for (final v in violations) {
            print('✗ ${v.fieldPath}: ${v.message}');
          }
        },
      );

      // 4. Throw if invalid (in CI mode)
      validationResult.throwIfInvalid();

      return ApiResult.success(response);
    } catch (error) {
      return ApiResult.failure(error);
    }
  }
}

Global Configuration #

void main() {
  ApiContractConfig.setup(
    onViolation: ViolationBehavior.throwInCI,  // Throw in CI, log otherwise
    enableInRelease: false,  // Disable in production
    logPrefix: '[Contract]',
  );

  runApp(MyApp());
}

ViolationBehavior options:

• log - Print violations (default)
• warn - Print warnings
• throwAlways - Always throw exception
• throwInCI - Throw only when CI=true env var is set
• silent - Ignore violations

🧪 CI/CD Integration #

Set CI=true in your CI environment:

# GitHub Actions
env:
  CI: true

Then configure:

ApiContractConfig.setup(
  onViolation: ViolationBehavior.throwInCI,
);

Contract violations will fail your pipeline before broken assumptions reach production.

📚 API Reference #

ApiContract #

ContractField #

ViolationType #

🎓 Examples #

Check the example directory for complete examples:

• main.dart - Full featured example with repository pattern
• post.dart - Simple model with annotations

📝 Version Upgrades #

Track contract evolution:

final v1 = ApiContract(version: '1.0', fields: {...});

final v2 = v1.upgrade(
  version: '2.0',
  added: {'avatar': ContractField.optional(type: FieldType.string)},
  removed: ['legacyId'],
);

🤝 Contributing #

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

📄 License #

MIT License. See LICENSE for details.

🔗 Related Packages #

• api_contract_generator - Code generator companion package

💡 Tips #

• Use ContractMode.strict during development to catch all changes
• Switch to ContractMode.lenient if backend adds optional fields frequently
• Enable throwInCI to fail builds on contract violations
• Disable validation in production builds for performance
• Use @optional for fields that might be missing
• Use @nullable for fields that are always present but can be null

⚡ Performance #

• Zero overhead in release builds (when enableInRelease: false)
• Minimal overhead in debug builds
• Efficient type checking and validation
• No reflection used

Made with ❤️ for Flutter developers tired of silent API breakages.