Show / Hide Table of Contents
    Note

    These docs are a work in progress. While conceptually correct, the diagrams/code samples on this page might not be 100% in line with the current implementation in Copper.

    Service versioning

    Essential for all systems that interact with other systems, automated or not. Also one of the hardest topics to master and often overlooked at the start. The problem is even compounded when there are long running processes (workflow) in the system.

    Context and problem

    During the life of an application, there are inevitability going to be changes that are required that are considered breaking any party that is integrating with that given API. If there is no good strategy in place to handle these changes, there is no way to gracefully allow integrators to update the integration to conform to the new specification.

    The symptoms of not having a strategy can lead to unexpected downtime, or the inability to make changes to the system after a while.

    Solution

    Have a solid versioning strategy in place. There is no automated solution for this problem and it will require communicating with the integrators and allow them to take the required time to update the integrations alongside the running system. After the integrations have been updated, have the ability manage the flow inside your system to route traffic from the old version to the new version.

    Versioning flowchart


    Versioning strategy









    Example

    The example below is a simplified version of the activate contract use case of the 365 project, focusing on the first payment flow.

    Case

    Payment provider now states that in 3 months, for all new first-payments it is mandatory to include a VAT number before a first payment can be requested. This should be considered a breaking change as it is a new, mandatory data member that is required to execute the use-case. Also, because the value of this member can’t be calculated, retrieved or otherwise derived the first payment process should be altered so the value is asked from the customer when starting the process. The payment provider has sent out a notification stating that the V1 API version will be kept up and running until the 3 month mark, which gives us time for a graceful deprecation of the V1 API in favor of the new, compliant V2 API.

    Problem

    Because of the way this business process behaves over time (the fact that the amount of time between operation 4 and 5 (see diagrams below) can be anywhere between 1 second and 7 days). Therefore it’s possible that one or more instances of this business process will be executed across different versions of the system (see sequence diagram for possible deployment times, relative to the execution timeline), as there could very well be a deployment of a newer version of the system while the process instance is idle between operation 4 and 5. In this case, this would result in step 6 not having the required VAT number since the instance of the process was created in a version of the system where it was not asked from the customer. In other words, if this process would be resumed against a codebase that doesn’t know any better than assuming a VAT number is present in the workflow at when executing operation 5, the execution would fail, either when retrieving the value from the workflow, when calling Payment Access or when invoking the V2 API of the Payment Provider (depending on where the first validation would take place).

    Possible solutions

    • Implement a compensation flow between step 5 and 6 that can ask the customer to provide their VAT number.
    • Manually compensate any active instance by adding the VAT number to the (already failed) message and resubmit operation 5.
    • Keep V1 of Payment Access (and possibly Payment Manager) active alongside V2 so any running process instance can be completed while initiating all new instances from the V2 endpoint so it includes the VAT number and thus will work against V2.

    Call chain


    Sequence diagram


    • Improve this Doc
    In This Article
    • Context and problem
    • Solution
      • Versioning flowchart
      • Versioning strategy
      • Example
        • Case
        • Problem
        • Possible solutions
        • Call chain
        • Sequence diagram
    Back to top Generated by DocFX