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.

Say you're building an API, you need to convert the objects you send in the response to JSON representation (removing certain properties like passwords, and modifying others like dates) you can use JSMSerializer to define how that happens automatically. But where JSMSerializer really shines is how it can deserialize data into PHP objects. Maybe you you are consuming a JSON feed, you can use this to convert each object in the JSON feed to an object. You do this by registering "handlers" for each object type. You can do all this configuration via annotations, XML or YAML (which you'll be familiar with if you've used Doctrine). It also includes an event system, which you can use to hook into modifying the data before serialization or right afterward it happens.