design practice for business layer when supporting API versioning

Question

Is there any design pattern or practice recommended for business layer when dealing with multiple API version.

For example, I have something like this.

http://site.com/blogs/v1/?count=10
which calls business object method GetAllBlogs(int count) to get information

http://site.com/blogs/v2/?blog_count=20

which calls business object method GetAllBlogs_v2(int blogCounts)

Since parameter name is changed, I created another business method for version 2. This is just one example but it could have other breaking changes for which it requires me to create another method to support both version. Is there any design pattern or best practice for business/data access layer I should follow when supporting API Versioning?

Answer 1

If you are going to mix v1 and v2 in one current code base you'd need to a have a reason for this. Typically this is because you are going to route old version method calls from your API service to new 'business object methods', this may involve some conversion and such.

If you are going to keep the v1 and v2 paths separate vertically (the code paths aren't sharing anything) you may as well let v1 be served by the old(er) version of your software.

Between v1 and v2 try to bundle API changes so you can offer your clients a document about migrating. API stability is typically appreciated.

Your example on it's own is -not- worth it, it's such a small cosmetic change try to not do those. Or if you do sneak them in while introducing other bigger changes.

While stacking up new interface for your v2 you could offer them early through some sort of extension mechanism, libraries like OpenGl do this.

Try to come up with a deprecation model for your older API surfaces. Supporting all old interfaces till the end of time is going to be hard and very costly.

If at all possible try maintain older version with old distributions of your software. If you can avoid to not mix API generations in one code base do so.

It's very hard to come up with a good interface on the first incarnation of your API surface. Clients may appreciate this, perhaps you can avoid the version management by allowing API instability and breaking changes through a alpha, beta cycle or 0.X releases.

Answer 2

Since the change you made is at the API layer, it should not affect the way the business layer gets blog posts. Just change the validation of the parameters sent to the business layer. To illustrate:

//I don't care about this API thing
class BlogService{
   public getBlogs(int count) {
      //...
   }
}

namespace API.V1

class Blogs{
   //...
   public getBlogs(MyParamterClass p) {
     if (p.hasParameter("count") {
         blogs = blogService.getBlogs(p.getParameter("count"));
     } else {
        //Invalid request handling
     }  
   }
}

namespace API.V2

class Blogs extends API.V1.Blogs {
   //...
   public getBlogs(MyParamterClass p) {
     if (p.hasParameter("blog_count") {
       blogs = blogService.getBlogs(p.getParameter("blog_count"));
     } else {
      //Invalid request handling
     }
   }
}

Answer 3

I recommend that you read about versioning first, because I think that you have misunderstood the aim of versioning.

Versioning is not about changing a number each time you change your code, it's about keeping a semantic pattern of numbers related to your code, so that you can track and trace better, manage dependencies, plan releases, etc.

And the best versioning scheme I've ever seen till now is the Semantic Versioning, or SemVer