5 Replies Latest reply on Jul 11, 2014 8:17 AM by Eric Wittmann

    Should API Management plans be versioned?

    Eric Wittmann Apprentice

      As I've been implementing API Management it has become clear that versioning of the various entities is going to be an important feature.  Currently both the Applications and Services can be versioned.  This allows multiple versions of these objects to be configured and modified and managed simultaneously.  Obviously this means that each Application will have access to a specific version of a Service.  It also means that the same Service can be deployed to the APIMan gateway multiple times with different version numbers.  Each version will have its own endpoint and policy configuration.  Once a Service is deployed it should be frozen so that Application developers know they can safely use the specific Service Version without it being changed out from under them.


      But what about Plans?


      Plans are essentially just specific Policies bundled up into a name.  It allows the group of Policies to be applied to multiple Services without having to configure each one separately.  It seems to me that the same concepts apply - we'll want to evolve our Plans over time.  Is there a use-case for changing a Plan mid-stream even though some Application might be using it?  That seems like a Bad Thing to do, since it would mean that terms and conditions could be changed without the Application knowing about it (think billing rates).  I think if Service owners want to change the terms and conditions then they will need to create a new version of the Plan and a new version of the Service.  They can then change anything they like and publish the new version.  At that point they must retire the old version if they no longer wish to support it.  We'll need a mechanism to notify Applications that a Service is going to be retired.


      So I'm coming down on the side of "Yes" as the answer to this question.


      Anyone else have thoughts?

        • 1. Re: Should API Management plans be versioned?
          Gary Brown Master

          Hi Eric


          Your conclusion sounds reasonable, but just want to understand the implications more.


          So an App would be configured to use a particular version of a plan and service? In which case, if an amendment was made to a plan - e.g. to update the billing rates, then what is to prevent the App remaining on the previous version - and therefore paying less?


          Wondering whether an App should have the ability to decide these things - possibly instead of versions it needs a concept of activation - so at a particular point in time, a new instance of the plan becomes active, and from that point onwards the App will automatically be using it?


          My concern with the use of versions is that the App configuration would then need to be updated to explicitly reference the new version.


          In terms of versions for service - I just want to be clear, this is not the versioning of the actual service, but of the configuration information associated with the service endpoint, and any service specific policies?


          As you mention, service configurations could be retired when no longer supported - but would need to understand the impact on Apps still configured to use that service. If a suitable solution could be found for this, then the same approach could also be used for versioning plans - i.e. when Apps need to move to a new plan version (with higher billing rate), possibly the old plan is retired - any Apps still referencing the old version are then either automatically bumped up to the new version, or become inactive as there is no valid plan available?


          Emails could automatically be sent out to App owners/administrators notifying them of pending changes such as this - and maybe they could have configuration options on the App to indicate whether version updates should be automatically accepted or require manual intervention.


          We may need to go through some dry runs to see how the impact of version changes at each level could impact the different users.




          • 2. Re: Should API Management plans be versioned?
            Eric Wittmann Apprentice

            Yeah I think I agree with you on pretty much all these points.  Ultimately there is a conflict between the Application owner and Service owner with regard to updating the details (e.g. billing rate, limits, etc) of a plan.  Service owners will want a way to update a plan to reflect new terms and conditions.  On the other hand, Application owners will obviously not want this to be done out from under them. 


            So I think you hit on exactly what I was planning (no pun intended) to do already, which is that Apps, Services, and Plans will be versioned and have a status.  The status of the particular version of these things reflects what can be done with it.  For example, once a Service is published, its state moves from Created to Published and is at that point locked and available to be used by Applications.  Same goes for Plans - they will have a state indicating whether they are locked for use or still being edited.  A particular version of a Plan or Service would remain available for an App to use until the Service/Plan owner retired it.


            So the workflow to update the terms/conditions of a Service would be:


            1. Create a new version of the Plan
            2. Modify the new version's terms
            3. "Activate" the new Plan version, which locks it
            4. Create a new version of the Service (since the current version is already deployed to the Gateway)
            5. Modify the new Service version to use the latest Plan version
            6. "Deploy" the Service to the Gateway, which locks the Service
            7. Retire the old version of the Service (triggering whatever actions we decide are appropriate for Applications that currently use the Service)


            I agree that we need options to streamline the process, particularly for enterprises that won't need to protect Apps from underlying Plan changes.  The above is really a strict use-case for more distributed enterprises or for a public version of apiman.

            • 3. Re: Should API Management plans be versioned?
              Gary Brown Master

              Sounds good for now.


              Some of the actions may need to be scheduled - e.g. deploying a new plan and service, and auto upgrading apps using an old plan to a new one - to enable things like price plan changes to "automatically" be updated.


              As a slight aside, in the current scenario I am assuming the App owner/admin will select the plan they wish to use. This is ok for the model where usage is billed based on the details associated with the plan.


              The other approach that may be required is where an App owner prepays for use of a particular Service under a particular Plan. In which case, the App owner would need to go through a separate stage where they do the financial transaction (out of scope for apiman at present), but then some other admin function establishes the link between the App/Plan/Service. In this situation, this relationship would need to be locked - possibly just readonly?

              • 4. Re: Should API Management plans be versioned?
                msavy Novice

                Do you think it could be useful to have the flexibility to allow more sophisticated users to define how they want these state changes to be implemented (essentially arbitrarily)? For example, by some kind of rules definition or perhaps a sufficiently flexible API.


                - X releases v2 of their Maps API, and in response they close access for new applicants to v1, reduce the number of requests for existing users, and after a set date start returning 410.


                - If payment is not received on the expected date then the user is downgraded to the basic package.


                - If request limits are reached, push a message with user info into the ESB (for consumption by an alert system).


                I'm not sure what the best approach for that would be. I just imagine it'd be very hard indeed to cover all of the possible user requirements with 'pre-baked' options.

                • 5. Re: Should API Management plans be versioned?
                  Eric Wittmann Apprentice

                  These are all great ideas for future versions of apiman. 


                  In the short term, I think some of these sorts of things will be possible externally, since all functionality in the management layer is available via REST api.  As we evolve the apiman functionality we can add internal support for these types of things.


                  I think you've introduced two separate features here - one in the management layer and one in the runtime layer.  The first is to allow the user to specify a list of rules they want applied when a particular version of a Service is retired.  We can call this a Retirement Strategy.  I like that idea a lot, actually:  [APIMAN-122] Support customizable Service Retirement strategies - JBoss Issue Tracker


                  The other feature is ultimately to fire interesting events from the policy engine.  I suspect the events will come from the policies themselves and will be very specific.  I think we'll need something like this perhaps:  [APIMAN-123] Create an Event Manager that policies can use to fire interesting events - JBoss Issue Tracker