Pagination: Web API Design 2nd Edition (APIGEE)

[Adrian Cole]

Starting another thread unrelated to nouns vs verbs :)

There's a section on pagination, and I was surprised to see this recommends an offset approach. 

I understand that in the context of "Web API" defined as a style that doesn't include hypermedia links, there'd be no "next" link. Hence, we need to advise how to paginate.

What are your opinions on steering developers towards "offset" vs "marker"?

-A

[Kristof Kotai]

Yes, that might be another thing to ponder about. From the API developer's point of view an offset-limit pair is always the best solution, because that can instantly be mapped to SQL queries. 

Whereas the Twitter API, which uses pagenumber and number of items to display is more convenient for the API consumer.

I have to agree, if the ebook's motto is "pragmatic REST", where the primary focus is on the API consumer, then Twitter's solution should be preferred... (Note twitter doesn't support that from v1.1, you will only have sinceID and count)

(I'm not sure what you mean by "next page link", you expect a functionality like that to be supported by an API? You do understand REST is stateless?)

[Glenn Block]

ATOM supports the notion of next and previous links. How does that violate statelessness?

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[Kristof Kotai]

I think he was referring to the interface... 

(Sure, you can return more information about how to get the next/previous resultset in the response, but the question was about the interface for pagination. Ways to specify that) (I think)

[Glenn Block]

I think I misread what you meant when you said "You do understand REST is stateless?)", but I think I get it now.

[Adrian Cole]

Thanks for the discussion, Kristof.  The farther this goes, the more it seems like the 'Web API' pattern described in the ebook represents a type of pragmatism especially when you are in control of the backend (ex. that it is simple database)

Comments on your thoughts below.

-A

On Sep 30, 2012 10:41 AM, "Kristof Kotai" <kotai....@gmail.com> wrote:
>
> Yes, that might be another thing to ponder about. From the API developer's point of view an offset-limit pair is always the best solution, because that can instantly be mapped to SQL queries. 

So, basically we are scoping this to implementations backed by a pattern of SQL :) Seriously, I think there isn't harm done in recommendations, just that clarity of intent and tradeoffs.  Ex. Web API in this case could mean an optimization for apis over databases with an acknowledged tradeoff on consistency across pages.

>
> Whereas the Twitter API, which uses pagenumber and number of items to display is more convenient for the API consumer.
>
> I have to agree, if the ebook's motto is "pragmatic REST", where the primary focus is on the API consumer, then Twitter's solution should be preferred... (Note twitter doesn't support that from v1.1, you will only have sinceID and count)

'changes since' seems a handy query esp for timeline based  models.  I'm not sure that is the same as pagination in the way I was thinking about it.  For example, a startDate is a qualifier to me...

>
> (I'm not sure what you mean by "next page link", you expect a functionality like that to be supported by an API? You do understand REST is stateless?)

Sorry, I could have been more clear.  Yeah, I was referring to atom style, which doesn't preclude embedding marker in the link href.

>
>
>
>
> On Sunday, September 30, 2012 6:20:40 PM UTC+1, Adrian wrote:
>>
>> Starting another thread unrelated to nouns vs verbs :)
>>
>> There's a section on pagination, and I was surprised to see this recommends an offset approach. 
>>
>> I understand that in the context of "Web API" defined as a style that doesn't include hypermedia links, there'd be no "next" link. Hence, we need to advise how to paginate.
>>
>> What are your opinions on steering developers towards "offset" vs "marker"?
>>
>> -A
>

[Adrian Cole]

On Sep 30, 2012 11:17 AM, "Kristof Kotai" <kotai....@gmail.com> wrote:
>
> I think he was referring to the interface... 
> (Sure, you can return more information about how to get the next/previous resultset in the response, but the question was about the interface for pagination. Ways to specify that) (I think)

Yeah, and particularly ways to specify a pagination interface that doesn't break in nosql backed apis.  Here's an interesting one on this topic and Cassandra and how to implement 'next'

http://blog.dynatrace.com/2011/12/05/pagination-with-cassandra-and-what-we-can-learn-from-it/

OpenStack also goes a slightly different path.  They, encode the how (marker vs offset) in a link in a collection type, which is somewhat atomy:

http://docs.openstack.org/api/openstack-compute/2/content/Paginated_Collections-d1e664.html

Food for thought.