CODEWITHSUNDEEP
apiapi-design
alexmcroberts
alexmcroberts

Reputation: 75

API Design - Ordering return data in an array

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.

Upvotes: 1

Views: 660

Answers (1)

Marc Baumbach
Marc Baumbach

Reputation: 10473

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.

Upvotes: 1

Related Questions