Skip to content

010-ADR: API Management

Architectural Decision Records (ADR) on implementing a bidirectional API management strategy for multi-platform issue synchronization.

1. State

  • Author(s): Sentenz
  • Date: 2025-01-13
  • Status: Proposed

2. Context

The project requires implementing a bidirectional API communication mechanism to synchronize issues between Jama, Jira, and Mantis. The system must handle CRUD (Create, Read, Update, Delete) operations, perform data transformation, mediation, conflict resolution, and ensure synchronization across the platforms.

  1. Decision Drivers

    • Data Transformation

      Ability to map and transform data structures between systems.

    • Mediation

      Ability to act as an intermediary that manages API communication and synchronization logic between platforms.

    • Conflict Resolution

      Ability to handle and resolve data conflicts arising from concurrent updates across systems.

    • Real-Time Synchronization

      Timely updates between API Endpoints to ensure consistent data across platforms.

    • Scalability

      Support for growing API traffic and extensibility for future integrations.

    • Maintenance

      Long-term sustainability and debugging capabilities.

    • Ease of Implementation

      Development effort and time-to-market.

3. Decision

3.1. Hybrid Approach

The selected approach combines Integration Platforms with Middleware. The hybrid approach balances flexibility, scalability, and cost-effectiveness, ensuring long-term sustainability while meeting immediate requirements. While integration platforms offer quick solutions, their cost and limited customization potential are significant drawbacks. API Gateways are excellent for API management but do not address the complexities of bidirectional synchronization.

  1. Rationale

    • Data Transformation

      Middleware provides full control over field mapping and data transformation between API Endpoints, enabling tailored transformation logic beyond what integration platforms support.

    • Mediation

      Middleware acts as the central intermediary, coordinating API communication and synchronization logic between Jama, Jira, and Mantis.

    • Conflict Resolution

      Custom middleware logic handles conflicts based on timestamps or version numbers, which integration platforms cannot fully accommodate.

    • Real-Time Synchronization

      Webhook integration through middleware enables event-driven, near real-time synchronization across all platforms.

    • Scalability

      Middleware can be deployed on scalable cloud infrastructure, and integration platforms like JCI handle Jama-Jira synchronization out of the box, reducing custom development scope.

    • Maintenance

      The combination of a managed integration platform (JCI) for standard workflows and custom middleware for complex logic reduces overall maintenance burden.

    • Ease of Implementation

      Jama Connect Interchange (JCI) accelerates time-to-market for Jama-Jira integration while custom middleware handles Mantis and advanced synchronization requirements.

4. Considered

4.1. Middleware

A custom application acts as an intermediary between API Endpoints, managing API communication, data transformation, and synchronization logic.

  • Pros

    • Full Control

      Full control over data transformation, mediation, conflict resolution, and API logic.

    • Event-Driven Integration

      Supports integration with event-driven mechanisms (e.g., webhooks) for real-time synchronization.

  • Cons

    • Development Effort

      Higher initial development effort compared to managed integration platforms.

    • Operational Expertise

      Requires operational expertise for maintenance and scaling.

4.2. Integration Platforms

Use a third-party integration platform (e.g., Jama Connect Interchange (JCI), MuleSoft, Boomi, Zapier) for synchronization.

  • Pros

    • Minimal Development

      Minimal development effort with built-in connectors for Jira and flexibility for customization.

    • Managed Scalability

      Scalable and monitored by the platform provider without additional infrastructure effort.

  • Cons

    • Cost

      High cost for enterprise-grade platforms.

    • Limited Flexibility

      Limited flexibility for highly customized transformations or conflict resolution logic.

    • Platform Support

      May lack native support for Mantis, requiring additional custom development.

4.3. API Gateway

Use an API Gateway (e.g., AWS API Gateway, Kong) to manage and route API communication between API Endpoints.

  • Pros

    • Centralized Management

      Centralized API management with built-in security features like rate limiting and authentication.

    • Endpoint Consolidation

      Simplifies endpoint consolidation and routing across systems.

  • Cons

    • Limited Transformation

      Not designed for complex data transformation, mediation, or synchronization logic.

    • Middleware Still Required

      Additional middleware is still required for advanced bidirectional synchronization between platforms.

4.4. Event-Driven Architecture

Use event-driven systems (e.g., Kafka, RabbitMQ) to trigger updates between API Endpoints.

  • Pros

    • Real-Time Updates

      Near real-time updates and decoupled architecture.

    • Scalability

      Scalable with additional platforms or events as the system grows.

  • Cons

    • Middleware Required

      Requires middleware for data transformation, mediation, and API communication.

    • Complexity

      Higher complexity in setup and management compared to direct integration approaches.

4.5. Direct API Communication

Each system directly communicates with the other using APIs without a centralized intermediary.

  • Pros

    • Simplicity

      Simple to implement for small-scale point-to-point integrations.

  • Cons

    • Manageability

      Complex to manage and scale, lacks centralized control as the number of systems grows.

5. Consequences

  • Positive

    • Full Control

      Full control over data flow and transformation through custom middleware.

    • Scalability

      Scalability to handle future integrations by adding new systems to the middleware layer.

    • Extensibility

      Ability to implement advanced features like logging, error handling, and conflict resolution.

  • Negative

    • Development Effort

      Higher initial development and maintenance effort for the middleware component.

    • Expertise Required

      Requires expertise in middleware development and API handling across multiple platforms.

  • Risks

    • Integration Platform Dependency

      Reliance on JCI for Jama-Jira synchronization introduces a dependency on a third-party platform; evaluate fallback options if the platform becomes unavailable or cost-prohibitive.

6. Implementation

  1. Develop Middleware

    Use a framework like FastAPI or Spring Boot for scalable, modular middleware development.

  2. Integration with APIs

    • Configure API clients for Jama, Jira, and Mantis.
    • Implement CRUD operations for issue synchronization.

  3. Data Transformation and Conflict Resolution

    • Design transformation functions for field mapping between systems.
    • Add conflict resolution logic based on timestamps or version numbers.

  4. Testing

    • Perform end-to-end testing with real data across all platforms.
    • Simulate conflict scenarios to validate resolution logic.

  5. Deployment

    • Host on a cloud platform for scalability.
    • Monitor using tools like Prometheus or ELK Stack.

7. References