API Facade Common Patterns: Errors
We've recommended that the best solution to the problem of exposing complex back-end systems' functionality in a way that's useful for app developers is to implement an API facade pattern.
In a previous post we looked at the basic steps to implement an API facade. In the next few posts, we'll examine common design patterns and the problems that the different patterns solve. We'll cover six common patterns: errors, stubs, URLs, versioning, data formats, and internal and external systems.
Errors "When I say errors, you say test-driven development"
Test-driven development involves building test cases and when they fail they help guide developers towards creating the right app. Because the black box is more stringently enforced with a Web API, this model and the errors are more important in the world of APIs and apps than in other areas of software development.
Design the HTTP codes and responses you want
Start with a facade, not connected to any internal systems yet and then get the error codes right. In previous Webinars, we talked about the 8 error codes we think are most important (shown below too). (The important error codes may vary for your domain.)
Get the error messages in place so that you can start to build your test suite, including the HTTP error codes and the payload response.
Control over the facade - raise the error
Sometimes you want to explicitly cause a raise to happen. Here's a useful trick and pattern we created for a large API provider which worked well. It involves putting a raise query parameter in your HTTP request.
It will raise that HTTP code. When you are building your test suite, this allows you to ensure your app logic handles exceptions properly.
Warning - don't let this make it's way to your production servers.
Test & implement - plug internal system into the facade
You've designed your set of HTTP codes from the outside in. You have a big internal system, which let's say was built on the .NET framework. Microsoft has an extension of the HTTP status codes - 449 Retry With. You will want to map the 449 to something more aligned with what mobile developers are familiar with today. To do so, you can implement a lookup table and transform the 449 code into a 404 error.
So, you started with the design intent - the HTTP codes and responses. You've exerted some controls over the facade by explicitly forcing the raise. And finally, you've tested it all by plugging internal system into the facade.
Next time, we'll look at other common patterns including data stubs and URLs.