Using total VS sum for API responses when querying lists of data

[brandonroberts]

For the REST API responses, when retrieving data from APIs, I'm used to getting some value for the "total number of records" returned in addition to a property that holds an array of the records.

For documents, the response returned currently is:

{
  "documents": [{}, {}. {}],
  "sum": 3
}

Traditionally, I've seen total used instead of sum to denote the total number of records returned by the query for the list. I think its worth considering changing sum to total or a name that includes total to align more with how other APIs return the count of records alongside the array of records.

AFTER:

{
  "documents": [{}, {}. {}],
  "total": 3
}

This would be a breaking change, but could possibly provide some sort of backward compatibility for existing users depending on the sum property.

The goal here is to reduce the number of things that diverge away from what other developers consuming REST APIs are used to seeing.

Some examples for reference

https://developers.google.com/youtube/v3/docs/activities/list#response
https://dev.twitch.tv/docs/v5/reference/users#get-users

Also interested in hearing what others think about this.

[christyjacob4]

This is a welcome suggestion. Backwards compatibility shouldn't be a problem since we have request and response filters 👍

[s3ppo]

i think its not good.. to much code refactor, for not much :(

[Meldiron]

I like Brandon's suggestion. People were asking about "sum" many times, their main concern was the difference between sum and doing documents.length. If total communicates it better than its server's total, then I would vote for this change.

[eldadfux]

Seems like the term sum is confusing from recent feedback we got. Breaking changes should have backward compatibility for older SDKs using request & response filters. If we want to make a change like this, it's better do it before 1.0 or at 2.0. Personal opinion is that if we don't do it now, it might remain confusing for years to come.

[gewenyu99]

Sum suggests some kind of arithmetic was performed, total suggests some type of headcount. I think total is the better choice here as long as there's a slow phase-in (warning that it's deprecated etc...)

[eldadfux]

Agree. We can aim this to 0.14 and add backward compatibility using response filters for devs who still want to rely on <0.14 structure.

[Meldiron]

I have created PR to address this issue. If anyone is interested in the topic, feedback and review would be highly appreciated 💖

#2848