11436 SSO

API Facade Common Patterns: Versions & data formats

Brian Mulloy
Mar 28, 2012

In this post in our series about common patterns in the API facade, we'll look at patterns for designing versions and data formats. 

Versions

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.

Data Formats

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.

Next time, we'll finish our review of common patterns by looking at how the API Facade is useful as a front for external systems in addition to the internal systems we've discussed in this series.

API Facade Common Patterns: Versions & Data Formats
In this post in our series about common patterns in the API facade <<link series>>, we'll look at patterns for designing versions and data formats.
 
 
Versions
Best practices and principles for versioning your API are described in <<<link design/versions post>>. 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.
 
slide fast/slow developer
 
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 allows you to point the request to the proper system to serve the response.
 
slide version
 
Data Formats
Different developers have different expectations for formats. For example, an HTML5 developer will want JSON responses while a Java developer depends on libraries to handle SOAP requests and responses.
 
Let's look at how a facade handles this for the Java developer. Take a developer who does a POST to get a collection of accounts. The facade mediates the POST into the more complicated back-end system and returns SOAP. This is a simple scenario not unlike the URL mapping scenario <<link previous post>>. There's no real data format mediation happening here.
 
 
slide1 SOAP
 
A more complex mediation happens for example when the developer does an HTTP GET and wants JSON in the response. The facade maps the SOAP to JSON on the response, probably using an XSLT. 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.
 
slide2 soap
 
 
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 <<links>>.  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.
 
{{Brian - a comment here about the shunts potentially making for a complex layer?}}
 
Next time, we'll take a look at how the API Facade is useful as a front for external systems in addition to the internal systems we've discussed in this series.

API Management Decision-Making Kit

Next Steps

 
 

Resources Gallery

News