Home/ Questions/Q 9234047
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-06-18T06:41:52+00:00

I currently have an API endpoint which returns an array of objects each containing

  • 0

I currently have an API endpoint which returns an array of objects each containing 4 variables in JSON format.

The size of the data ranges from 500kb to 5mb – depending on the number of records. In order to reduce the size of the return, we’re considering removing the labels from the objects, and returning an array of arrays.

E.g.

[{propertyone:123,propertytwo:456,propertythree:789,propertyfour:012},etc,etc,etc]

would become

[[123,456,789,012],etc,etc,etc]

We would then document that array position 0 is to considered propertyone, etc. There may be a point in the future when this API becomes public. Is it considered better practice to leave the names in, or would serving a documented API with an enforced order suffice.

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    Well documented APIs are often the best APIs. Having external documentation for your API is important, but the data you return needs to be documented as well, and nothing beats self-documenting data.

    I think by removing the property names, you’re going to lose this self-documenting entirely and you could end up limiting yourself in the future as well. For example, consider only wanting to return partial data, how would you represent it without those property names?

    In addition to the documentation, if you’re returning JSON then depending on the consumer’s environment, providing those properties could give them a natural model to work with. Consider JavaScript as an example, if they simply parse your response into JavaScript objects they essentially have a client-side model implemented for free and that will make it a joy to work with your API.

    Nonetheless, speed is important and I would suggest looking into different measures for reducing the size of the return. Often a common solution to this is providing paged results, requiring a client to perform additional requests if they desire more data. Also, depending on the shape of your data, you could benefit greatly by using something as simple as GZIP compression on your responses.

    While designing an API, as long as you document it and it works as described, normally anything will suffice. However, the API that empowers the consumer is the one that succeeds.

    • 0