I'm planning a series of pull requests for JSON API, many of which are related to issues already raised on Github. I've summarized them here to emphasize common themes:
- Center requests and responses upon primary resources and reference other resources relatively.
- By default, make as few assumptions as possible about what the client wants.
- Allow for a number of degrees of flexibility, all of which are optional, so that the client can customize the response.
- Provide sufficient recommendations for common API design patterns to inform default implementations.
I touched on a lot of these topics in my talk "Building Ambitious APIs with Ruby" at the Burlington Ruby Conference this summer: video + slides