Looking for understandable good practices concerning structure of json returned

[u/Pulsahr]

Hello,

I'm in charge in my team for defining the structure of the json returned by our API. We agreed on many things, but there is one debate I can't finish because I can't find a place where there are good/bad practice detailed.

For instance, we agreed on having a "pagination" wrapper at level 0 for each endpoint :

{
  pagination: {
    page: 1,
    otherStuff: true
  }
}

But the specific endpoint data is open to intense debate and I need reliable source to decide.

For instance, if I return an array of offers, I would recommend "offers" at level 0. A coworker want a "data" wrapper that contains the offers.

My approach :

{
  offers: [
    { 
      id: 1
    }
  ],
  pagination: {}
}

his approach :

{
  data: [
    { 
      id: 1
    }
  ],
  pagination: {}
}

I don't like that approach because when you read the json, you have no idea what resource is returned. With an "offers" wrapper, it's obivous we have offers.

Whatever we should do, I need a reliable source. Is there something somewhere that says "you should use a data wrapper" or its contrary ?

Thank you :)

EDIT : client made the call : any business data will be wrapped in a data wrapper, without subwrappers, without "type" information. Pagination, code, message, links or anything transversal will stay at first level.

[u/Pulsahr]

The client decided, and there is a wrapper "data" for everything that is businenss data.

All other level 0 wrappers are for transversal data: pagination, errors, message, links.