The basics of paging are already described up on the PLM 360 online help. But for today’s article, I’d like to go a bit deeper. I’ll also be answering some “why did they do it that way” style questions.
Which endpoints support paging?
If an endpoint supports paging, it will say so in the documentation. In most cases, it’s a GET call, like when getting the items in a workspace. Page parameters are passed in as query parameters, which are part of the endpoint API documentation. If the documentation doesn’t list any query parameters, then paging is not supported. If you try to use paging query parameters with an endpoint that does not support paging, you will get a GEN_PAGING_NOT_SUPPORTED error.
Sometimes a POST call will support paging. In these cases, the input payload has the paging parameters, not the query string. Another thing different about POST calls is that the nextUrl and prevUrl values are null in the returned PagedCollection. Since POST calls require data in the body of the HTTP request, the URL doesn’t contain enough data to run the operation.
Going off the edge of the world
There is no upper bound to the “page” parameter. You can grab page 100000 if you want. The call will succeed even if the object list finished at page 3. Go ahead, try it. Try the URL api/v2/workspaces/1/items?page=99999999 in your tenant.
You get back an empty set. You don’t get a nextUrl for obvious reasons, but it does provide a prevUrl. This is because REST paging doesn’t yet have a totalCount feature (sorry). So REST doesn’t know if the previous page contains items or not.
PagedCollection for endpoints that don’t support paging
All collection endpoints return a PagedCollection even if they don’t support paging input parameters. This is a bit counter-intuitive, but there are a couple of good reasons why we went with this approach:
- Consistency across the API.
- Allows paging to be added in the future without changing the return schema, which would be a breaking change.
Leave a Reply