JSON Design Principles (Part Four of Three)

As a followup to my own series on designing JSON, I thought I would add a fourth entry in the trilogy:

• Part 1: An approach to designing JSON schema
• Part 2: JSON tools and standards
• Part 3: Lessons learnt from the JSON schema I've worked on

I came across HTTP API design guide extracted from work on the Heroku Platform API.

This is interesting in part because some of the design principles it espouses (use objects a lot to group things together e.g. owner.id) somewhat contradict some of the design principles I came up with (keep things as flat as possible e.g. owner_id). Just as I do, this Heroku guide emphasizes that this is a set of principles, not the only way to do things.

This guide also discusses how to construct an API (e.g. Require Versioning in the Accept Header). I've designed a handful of REST APIs, learning more each time, of course. The advice in the Heroku guide rings true to me and covers quite a few ideas I'd like to try out myself, next time.