Re: Proper Use of Pagination and Caching

[Nick Floyd]

It's great that your team member is thinking about the end
implementation,however it has been my experience that being clever
like that tends to lead to confusion and frustrated consumers. I think
having a hard, consistent interface (such as, page count caps at a
certain # and start on page 1 unless specified with the consumer being
able to lower the count) would lead to happy consumers.

As for caching, it depends on you implementation and the understanding
you have between your primary app and the api users. I generally, by
default implement some spatial caching (if consumer requests page 2 of
set x, I will cache pages 1 & 3 out of band, anticipating the
consumers needs.

-nick

On Dec 22, 3:27 pm, Scott Sayler <scottsay...@gmail.com> wrote:
> I'm currently working through some requirements and my teammate and I
> are at a crossroads in terms of how we want to architect our caching
> and pagination.  Our team is looking to architect a solution that will
> include native applications on both iOS and Android devices.  We are
> also looking down the road for mobile sites using HTML5.  Given that
> we are using an API management tool that has caching abilities, we are
> struggling with where the pagination logic should reside.
>
> One team member believes that since presentation layer resides at the
> native applications, it is up to the native application to tell the
> API management tool how many records to return and where to start to
> retrieve the cache records (i.e. return 25 records starting at
> position 1).  The other team member believes that the API management
> tool should identify the type of device based upon the header
> information in the HTTP request and then decide how many records to
> return from the cache (i.e. API management tool identifies that an
> Android device sent the request for data, so return the standard 15
> records for Android).
>
> I can see the merits of both approaches, but I wanted to get the
> perspective of the experts on this forum.  Any guidance would be
> great.
>
> Also, side question.  Is there any standards on how long you should
> ideally keep the cache active for removing the records?  Thanks.

[SS32000]

Thanks for the feedback. I guess I believe it should be pushed out to
the presentation layer (native device) and create the consistent
interface where the application/developer tells the service how many
records it wants. This provides the API provider with the ultimate
flexibility because they only support one API and leave the display/
user experience to the device specific code. In my mind it makes
sense to perform the following:

1. iOS application makes a request with the cache key (123), page
number (1), and number of records (10) to retrieve
2. API management tool grabs the full record set based upon the cache
key (if it is cached already) and filters to pull the first 10 records
(page 1 and 10 records)
3. iOS displays the ten records and if it needs to retrieve more, it
makes the same call but updates the page number (i.e. cache key = 123,
page number = 2, number of records = 10)
4. API management tool grabs the full record set based upon the cache
key (i.e. it does not hit the back end servers again) and provides the
application the next set of records (records 11-20 because it knows to
start on page 2 and the intervals are of 10)

I think the above makes more sense than using the API management tool
to understand every type of device and it's display parameters. Is
the scenario I have laid out above what you were envisioning Nick by
having a hard interface? Thanks.

[Brian Mulloy]

Nick wrote:
> it has been my experience that being clever> like that tends to lead to confusion and frustrated consumers.

i agree with Nick. if behavior changes based on the client then the
API will feel non-deterministic and frustrating.

Scott wrote:
> I think the above makes more sense than using the API management tool
> to understand every type of device and it's display parameters.

the behavior you outlined, Scott, looks solid to me.

[SS32000]

Brian,

What about handling HTML5 in the scenario I laid out above? From a
native application it makes sense to control the parameters, but how
would HTML5 factor in there? HTML5 could be used across a variety of
mechanisms (mobile, desktop browser, etc.). Thanks.

[Nick Floyd]

Ask yourself these two questions regardless of the technology
consuming your API: "What do we define as frequently accessed data?"
"What do our consumers define as frequently accessed data?" Those
questions are a matter of judgment and engineering. What resources
should be in a cache, how long should they be in the cache, when
should we use temporal caches or spatial caches, do we prime our cache
or use demand caching and so on.

Possible caching architectures you could use...
Temporal cache is good when you can stamp the resources with a
"freshness" date - something like daily reporting data

Spatial cache is good when you use paging (like your example above)
and you're aware that your users generally drill in 2 or 3 pages deep

Priming cache is good when you know that the data will always be
requested - something like user information for login

Demand caching is good when you really don't know what data will be
used but you know it get's reused - something like products in a
catalog

Possible caching protocol implementation...
Given that the API is web based and depending on the types of
resources that you're wanting to expose (if they are optimistically
updated or not, or more immutable) then you can use Etags or entity
tags to drive caching behavior - keeping in mind there are different
types of caching that provide different functions.

Let's say your web app, ios app, android app and so on all need basic
information about the logged in user's organizations ( let's say you
have a multi-tenant SaaS model). Generally information about various
organizations do not change; they are often simi-static entities. So
you could implement something like:

1. The first user hits the API through web app requesting
"organizations/1" - the API returns the resource to the web app with
an Etag header => Etag: "12341234234214"
2. Now the web app (commonly referred to as the consumer or client
app) can choose to cache the resource with the Etag
3. Later a user from the same organization "logs in" to the consumer
app so the app makes a request to the API using the same organization
uri (organizations/1) and passes the "stored" Etag with the request
using an "If-none-match" http header (or others) - so something like
If-None-Match: "12341234234214" (side note, if you're dealing with
multiple resources you can pass in a comma delimited list of Etags
4. Here's where the HTTP magic happens: The API looks at the request
uri and checks the Etag, if it matches you send back a 304 Not
modified without a message body, if it does not match and the resource
has a different or no Etag associated to it then the response body
will be the resource with the new Etag.

As you can imagine this results in huge savings with interactions
between any client and the API: payload reduction, HTTP noise,
understood protocol (rfc2616), API work, API to data store work and I
am sure there is more.

Have a look @ rfc2616 on Etags: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19

I hope that helps - I have found with the APIs I have had an
opportunity to work with and create... the closer I stick with chapter
5 of the Fielding dissertation (http://www.ics.uci.edu/~fielding/pubs/
dissertation/rest_arch_style.htm) and rfc2616 (without going
overboard) the happier my consumers are because they can anticipate
the behaviors of my APIs.

Sorry if this is a bit much more information than you were looking
for, I love your question; sometimes, it seems, that caching / paging
is a last thought in APIs out in the wild.

[Brian Mulloy]

the API ought to be the same no matter the client. for example,
JavaScript in the HTML5 apps ought to use the same URL as the iOS or
Android apps.