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.

Swagger is a popular open source spec to auto-generate very nice looking API documentation with the ability to easily try any API request. You can use the Swagger's own swagger-core framework for node.js, Java or scala, but there's is also support in many other languages because of the strong open source community behind it for other languages like PHP, Ruby, Python, etc. Swagger's biggest open source competitor is Mashery's I/O Docs.

Makes it easy to visualise and construct custom HTTP requests to test with any RESTful web service. Syntax highlighting, custom headers and construct POST or Put body via raw input.

Great video and nettuts article from Phil Sturgeon on how we can use CodeIgniter to create a RESTful API for your existing web applications, and demonstrate how to interact with your own API or other RESTful web-services, such as Facebook and Twitter.