Securing JSON APIs With Wrapper Objects

Security is a top priority. Leading companies such as Zappos, Dyn, and Etsy use Database Performance Monitor (DPM), a cloud-based database performance management service to monitor MySQL in production designed for performance, isolation, and security. Even small decisions can make a big difference. One of those micro-decisions is making all of DPM's APIs return a top-level object in JSON, never a top-level array. This is to avoid an old, obscure, unlikely, but still possible JSON security vulnerability. If you've never heard of JSON security vulnerabilities, you should go read Anatomy of a subtle JSON vulnerability before continuing. Now that you’ve read that, you know a lot more than most people about JSON and security. Although modern browsers have fixed the underlying vulnerability, older browsers are still in use, and so although it’s not as convenient, we think it’s still important not to leave this potential hole open to exploit. What does this look like in practice? It simply means APIs that return lists of objects wrap the list in a top-level object. For example, suppose you have a Person data type in your API. If you GET a single Person, you might end up with the following JSON response:

{ "name": "John Smith" } 

All’s well so far. But what if you want a list instead of a single one? The most intuitive way might be as follows:

[{"name": "John Smith"}, {"name": "Jane Smith"}] 

But that’s exactly the situation we need to avoid. As a result, all of DPM's APIs use a top-level object for lists such as this, with a single data property:

{"data": [{"name": "John Smith"}, {"name": "Jane Smith"}]} 

Some people object to this; it seems inherently wrong to them. Our view is that security trumps elegance, and it’s not a big deal for consumers of the API to look for a nested list instead of a top-level list. Developing a large-scale service-oriented application involves making lots of decisions, many of which include tradeoffs. Here are a few resources you may find interesting:

• HTTP API Design Guide based on lessons learned at Heroku
• Microservices - not a free lunch and Microservices - the good, the bad, the it works