API Facade Common Patterns: Versions & data formats
In this post in our series about common patterns in the API facade, we'll look at patterns for designing versions and data formats.
Best practices and principles for versioning your API are described in RESTful API Design: Tips for versioning. Here we'll focus on designing for a scenario in which you need to support more than one version. This is common scenario especially in certain phases of your API's life cycle.
The way to handle this with a facade is to design it such that regardless of which request comes into the facade, you have a shunt in place that points the request to the proper internal system, which serves the response.
Different developers have different expectations for formats. For example, an HTML5 developer might want JSON responses while a Java developer might depend on libraries to handle SOAP requests and responses.
Let's look at how a facade handles this for a developer who needs SOAP. Take a developer who does a POST to get a collection of accounts. The facade mediates the POST into the more complicated internal system and returns SOAP. This is a simple scenario not unlike the URL mapping scenario. There's no real data format mediation happening here.
A more complex mediation happens for example when the developer does an HTTP GET and wants JSON in the response. The facade maps SOAP to JSON on the response, probably using XSLT. Note that the developer has no knowledge of the complexity or the mediation and only knows that they are getting the right format data returned for their app.
Data formats is the last pattern in our summary of the 5 common API facade patterns. We've covered errors, data stubs and URLs in previous posts. Hopefully you've seen how a handful of common patterns allows you to surface simple interfaces to complex systems in a number of contexts, and in predictable and reusable ways.
Simple interfaces to complex systems
One reaction to the facade pattern is that it adds a layer of complexity to the technology stack. Whether or not an organization uses the facade pattern, there is complexity that must be addressed between the app developer and the API. Often this complexity is buried within individual systems and difficult to track. So there is complexity on top of unknowns - which is bad. The facade pattern actually helps to create order where there was none.