We have a service to return messages. We want to limit the number returned, either allowing the caller to specify the max number to return, or else to use an internal hard limit. We also have thought it would be nice to include in the response whether more messages are available. The “best” way to go about this is not clear.
Here are some ideas so far:
- Only set the “more messages” indicator if the user did not specify a max limit, and the internal max limit was hit.
- Same as #1 except that “more messages” indicator set regardless of whether the internal hard limit is hit, or the user-specified limit is hit.
- Same as #1 (or #2) except that we internally read limit + 1 records, but only return limit records, so we know “for sure” there is at least one additional message rather than “maybe” there are additional messages.
- Do away with the “more messages” flag, as it is confusing and unnecessary. Instead force the user to keep calling the API until it returns no messages.
- Change “more messages” indicator to something more akin to an EOF indicator, only set when the last message is known to have been retrieved and returned.
What do you think is the best solution? (Doesn’t have to be one of the above choices.) I searched and couldn’t find a similar question already asked. Hopefully this is not “too subjective”.
3
Usually, it helps to look at how others might have done something similar already, and see if that can be used. This is typically how patterns emerge in software (and some are then even formalized as ‘design patterns’).
I am most familiar with oData, and in ASP.NET, oData supports both client and server side limit. However, it is up to the servers to decide if they want to set an upper limit even if client specified a response size. For example, if the client asked for a million messages, the server may still choose to limit it to 100 to save the bandwidth costs, and not run into performance issues, etc. So oData implements it the following way:
- Client can specify how many records to return via the
$topparameter. - Client also specifies how many records to skip via the
$skipparameter.
Thus if a client wanted results from 1 to 20, it would set $top=20 and issue the query. For the next page, it would skip the first 20 and thus set $skip=20&$top=20.
- The server can also limit the results.
- In that case, in the response, it puts a link for the next page, using the
odata.nextLinkelement.
Thus if a client issued a query and did not specify any limit, the server could decide to send 50 rows and then along with the result, send the query for the next page:
"odata.nextLink":"http://localhost:23645/api/Movies?$skip=50"
By setting $skip=50, the next query will start at item 51. The link I provided earlier to MSDN blog has more details.
You could consider utilizing one or both of these approaches, especially if you are returning JSON responses. If you have developers coming to use your service, they might be able to more easily understand (esp. if they have worked with oData). Or you could pick whichever framework is most likely to be known to your developers, and model based on that.
FYI, you don’t have to necessarily model both either. However, in this case, it seems quite likely that if you’re able to model $top and $skip, then creating the next page link is quite trivial if you choose to limit on the server.
2
As a consumer of API’s, my preference would be 3 or 5. While it makes coding easy to just go until you get nothing, API requests can be costly. The choice between 3 or 5 I think would really come down to the penalty for retrieving limit + 1 items. If there is very little overhead to the backend to check, then it is a very friendly thing to let the user know before they make one more needless request.
1
Maybe you can offer some more flexibility to the client. Your request can have a startWith element and the number of messages to retrieve noOfMessages. Your response can have a field called totalMessages that will held the total number of messages. This will allow you client to have something similar to pagination. startWith will default to zero; noOfMessages to a decent value.
For example if you have 56 messages, if the client wants to retrieve batches of 20s, they can send the following calls:
Request 1:
noOfMessages: 20
Response1:
...message list...
totalMessages: 56
Request 2:
startWith: 21
noOfMessages: 20
Request 3:
startWith: 41
noOfMessages: 16