Pagination of Large Computed Responses

[jlnaps]

I wanted to have a discussion around what we feel is the best way to handle returning potentially large responses that are computed as opposed to just reading from a large collection of objects.

Simply paginating these requests can be tricky, as the computation is sometimes expensive and would require rerunning it whenever the users calls in with a new page seems like it could add up rather quickly.

After some smaller discussions, it seemed like we were able to determine the following possible solutions:

1. We could just not paginate the result in this case.
2. Paginate as normal and deal with the computational costs.
3. Compute result on the initial call, store locally, and then provide the user some kind of scrolling functionality.
4. Compute the result asynchronously and give the user an ID and endpoint to monitor the result of the request.

What are our general thoughts around this idea and how would we like to generally define this behavior?

[shifr]

@jlnaps, could you please provide some examples for the use case?

[jlnaps]

We have an endpoint that takes, as input, a potential change to the entity state of our service, compares it to the current state, and outputs information to the user such as which changes are equivalent to the current state, which changes are different but compatible with the current state, and which changes conflict with the current state. Making conflicting changes require special actions from the user.

The size of this response is dependent on the size of the input, i.e. the potential change. If they are proposing just changing one entity, the response size will be one. If they are proposing changing 1000 entitles(unlikely but possible), the response size will be 1000.

But unlike a collection, where we just grab the objects and return them, here we are computing this response against the active state.

[ca0abinary]

@jlnaps Jira has an interesting solution for this problem that might work for you. It expects a spreadsheet (template based) to process large imports of issues. Using this pattern is it possible for all the compatible changes to be automatically processed and only a subset of exceptions presented to the user? Video example

[travisgosselin]

@jlnaps it sounds like you're talking about an "action" style, non-restful endpoint that needs to return a collection?
https://spscommerce.github.io/sps-api-standards/standards/url-structure.html#actions

If so, then I think the answer largely depends on your implementation and less on the standards.

Generally speaking, if you can pivot to think about the action as a noun with its own resource, then you can apply the API Standards much more closely. This would imply shifting /users/{id}/activate to something more restful like /users/{id}/activations/ where activation is now a proper collection that. Of course, as a proper collection, you would need to provide a performant way to continually access the activations by user id that likely did NOT regenerate them every time.

Keeping it action style endpoint is less desirable, but largely something you'd need to decide on your design. Keeping it as action style endpoint might infer that this is not something that you can page through, give all the results. I'd almost suggest that if pagination is needed, that you consider moving to more restful style, which might involve more async behavior where you get an ID, its processed in the background and then results can be paged through RESTfully.

[jlnaps]

So looking through the api standards, I would say that we definitely fit into this bucket:

// Acceptable - A verb if this is the only endpoint, the model does not represent a domain (i.e. is a one time analysis report), and is a single action performed.

So I think keeping this endpoint as an action is appropriate.

From there, I think my question becomes this:

If we are implementing an endpoint as a synchronous action, is pagination needed on the response? We are generally coming from the position that we don't want pagination on the endpoints right now. In fact, one of our consumers are actually talked with us about how they would prefer that we not. We just want to make sure that don't run afoul of any standards in doing so.

Should we define patterns around asynchronous operations in the future, we could revisit these endpoints and make changes as appropriate.

[travisgosselin]

If your intention is to continue with an action-style endpoint, I think not-using paging is most expected. If you did want to implement paging, that would push you towards a different more RESTful model, async with a series of endpoints. So to be clear, returning a collection from an action-style endpoint without paging input or output seems fine as long as you never plan to add pagination. If you did further discussion on RESTful structure would be appropriate for defining new endpoints at that time.