REST API Design: Avoid future proofing with the JSON junk drawer

The first in an series "Not Good APIs", where we look at common 'REST' API design flaws that cause usability or other issues.

This episode looks at problems with flawed future proofing strategies, by way of arrays of objects with keys and values.

API developers sometimes use this thinking that they can make changes without affecting the contract. We'll look at how JSON _is_ key-value pairs, and just adding a field to responses is still a backward compatible change, and a far more usable solution.

References:

Zendesk API - User Defined Custom Key/Value

APIsJSON.org

JSON

Attribute-value pairs aka key-value pairs

Covariance and contravariance

Petter Graff

Lo-dash

[mloskot]

Excellent talk, especially for an API newbie as myself, and I'm already hungry for more. Thanks!

[apiworkshop]

FYI added Gabriel's improved Javascript for finding keys in arrays as an annotation at 6:47. Thanks Gabriel!

[apiworkshop]

Eric Jain my perspective on this is really as a counter to a percived 'future proofing': if a field in the key-value collection changes, your client code is still going to change. If you add a field to the key-value collection, the client still has to add code. Granted, you don't have to change your mapping model, but it would still be a breaking change. Your client code is still ultimately going to be more complex and mapped to strings rather than a static model.

[MotoWilliams]

The interesting cross-over here is that those Hashes That Time Forgot™ are a code smell in a lot of programming languages as well.

Looking forward to more episodes

[ejain]

The key-value structures may not make much sense in JavaScript, but can make life easier for anyone who is consuming the JSON with an object-mapping library like Jackson (Java), and doesn't want to be forced to deal with dozens of fields that are constantly changing.

[DouglasSims]

Good talk.  I can't think of a good reason to ever use words like "key, " "value, " and "attribute" in a JSON structure, though it's certainly done.

[techieplex]

Its bad that not seeing any new videos

[coreyledford]

on this video. 

Yeah but complexity just means I did it better and I'm smarter than you if you can't figure it out! Right! Right? T.T

I did some work where the client-side engineer was driving the JSON design for some reason (I was server-side, gritting my teeth every time it was allowed to pass through design) where everything was pretty much an anonymous object { "name":"blah", "[type]":[actualValueICareAbout] }

Want to validate a single property? PITA.
Want to validate the whole entity? GL LOL
Want to use magic parsing of some sort? NOPE

And the issues permeate all the way up and down the pipeline. This affects friggin EVERYTHING unless you're doing all the heavy lifting up front, which sucks from an MVC perspective. Massive payloads that could be 80% smaller end up causing extra functionality where we're sending back multiple responses, etc.

Good stuff. 

[Viverfm]

bem vindo ao paypal o melhor empresa de pagamentos eletronicos aqui squi voce tem a maior cobertura virtual