Encapsulate external JavaScript library

Question

I am about to develop a ASP.NET MVC 4 project that will make use of maps. Our company has it's own map API which is very basic at the moment, but is intended to be further developed in future to match some specific customer needs. The project will have a mobile/tablet interface in addition to it's web interface and needs to be developed now. So we have planned to start use the Google Maps v3 API.

I would like to encapsulate the API, so our applications don't have Google API specific calls. The same approach as if I would like to use som external API i C# and wanted to encapsulate it in order to be able to switch API in future without having to re-code the entire application.

But I haven't been able to find similar examples, so the following questions arise:

1. Is it a good and reasonable approach? Let me hear your pros and cons.
2. How would it be done in practice?

Answer 1

Is it a good and reasonable approach? Let me hear your pros and cons.

Typically, I would advise against preemptively encapsulating a library or API - it's usually a bad case of YAGNI, as it complicates your design for dubious gains. Most of the time what happens is that the wrapper ends up being tied too closely to what it's encapsulating, so that even when you actually do end up switching to some other library or API, you have to change all the client code because the new one is too different and matches very badly to your wrapper.

In this case, it might be defendable as you have relatively concrete plans of switching the underlying API and already a second implementation, albeit an incomplete one. If you do it, I would very much recommend looking closely at at least one other complete map API (like Bing Maps) to ensure your API could work with it.

How would it be done in practice?

The best approach is probably indeed a facade: don't try to write a wrapper that exposes all the functionality of Google Maps. Instead, create an interface that contains only the map-related functionality your application needs and thus represents an abstraction layer. It will probably aggregate calls as well as translating them and contain some logic of its own.

Your chances of porting it to a different map provider without having to change the application code are much better than with a thin, fully-featured wrapper.

Answer 2

If you want to simplify the first layer of the front-end development of your application, it does sound like a good and reasonable approach (if well-designed: it improves maintainability, scalability, etc.).

I believe that you want to implement a FACADE, this article here should explain just what you need: http://www.joezimjs.com/javascript/javascript-design-patterns-facade/

You can define the Facade pattern as a piece of code that simplifies a more complex interface. You can pretty much call any form of abstraction a facade.