Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
3  

3 Answers 3

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
     }
   }
}
share|improve this answer

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

share|improve this answer
    
Versioning an API is necessary for clients to handle breaking changes. If the interface changes so must the client, and an older client may still need to connect to an older interface until it's upgraded. –  Matt S Sep 2 '13 at 17:56
    
What part of what said was inconsistent with what you mentioned @MattS? –  Saeed Neamati Sep 2 '13 at 17:58
    
Instead of answering the question you say maybe the poster shouldn't use versioning. Nothing in the question implies versioning is inappropriate. –  Matt S Sep 2 '13 at 18:08
    
Then I suggest that you read my answer twice. I simply suggest that the OP is misusing the versioning concept. Nowhere I've mentioned that he shouldn't use it. –  Saeed Neamati Sep 2 '13 at 18:29
    
I've also recommended the most up-to-date versioning system. How could I ask somebody to not use something, when I present the thing? –  Saeed Neamati Sep 2 '13 at 18:30

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.