Building a JSON API, you should be trying to follow the JSON API spec. Save your team the effort of arguing the best response format. It reached version 1.0 earlier this year, so it's safe to say there won't be too many big changes now.

It defines a standard for what the offsets in the json response should include: a resource is returned in "data", pagination in "links", errors in "errors", additional data in "meta", and a standard for including other objects aka "compound documents" in "relationships"/"included", so that instead of embedding other resource objects inside the main resource it flattens the graph of objects to eliminate duplicate data in the response (eg. the same user can be both the post author and a comment author).

If you're curious about some of the design decisions or how it compares to HAL, check out the FAQ.

Before you start coding your API, you should model it out; see what kind of endpoints you're going to need and what kind of parameters they're going to accept. RAML is very colorful visual way of modeling an API.

I/O Docs is a live interactive documentation system for RESTful web APIs. Open sourced by the talented API guys at Mashery. I/O Docs is a lot like Swagger except I/O Docs isn't just a spec, it's the interpreter as well and it's written in NodeJS.