Recap

• A YouTube for poetry, API first
• We have GET, PUT, POST, DELETE and PATCH
• GET can list or retrieve one poem
• Listing gets all of them

Recap

List poems (GET):

$ curl http://localhost:8080\
    /api/v1/poems
    

["this-is-a-photo", "a-question"]

Why paging?

• Mainly to avoid server load
• Scalability: no unbounded operations
• Most clients will show in pages

Page numbers

/api/v1/poems?page=3

• RESTful: collection is resource
• Easy to understand
• Easy to implement
• Unstable

Page numbers

/api/v1/poems/page/3

• RESTful: page is resource
• Easy to understand
• Easy to implement
• Ambiguous?
• Unstable => not that RESTful

Archives

/api/v1/poems_archive/2009/11

• RESTful
• Stable
• The Atom Way:
• Unstable pages
• Stable archives

HTTP style

Use headers instead of URL:

$ curl -i \
    --header "Range: page=3" \
    http://localhost:8080/api/v1/poems

HTTP style

Response:

HTTP/1.1 206 Partial Content
Content-Type: application/json
Transfer-Encoding: chunked
Content-Range: page=3
Date: Fri, 15 Nov 2013 09:50:51 GMT
Server: localhost

HTTP style

• Uses HTTP built-in capabilities
• Stretches the concepts a bit
• Fatal: can't experiment in browser

The Twitter Way

/api/v1/poems?since_id=foo&count=20

• RESTful: collection is resource
• Provide last-seen id as since_id
• Client controls page size
• Stable
• We limit count to manage load

The Twitter Way

def listpoems( db, count, since_id ):
    ids = ( id for id in db.poems )

    # Skip up to since_id
    ids = itertools.dropwhile(
        lambda id: id != since_id, ids )

    # Skip 1 more
    ids = itertools.islice(
        ids, 1, None )

The Twitter Way

def listpoems( db, count, since_id ):
    # ...

    # Stop when we reach count items
    ids = itertools.islice(
        ids, 0, count )

    return ids

The Twitter Way

# poems.py
def GET( self, urlid ):
    # ...
    return json_poems.GET(
        self.db, clean(urlid),
        web.input()
    )

TODO: Hyperlinked

• Getting to other pages
• Response should tell you how
• The Atom way:

<link
    rel="next"
    href="...feed.atom?page=2"
/>

More info

Videos	youtube.com/user/ajbalaam
Twitter	@andybalaam
Blog	artificialworlds.net/blog
Projects	artificialworlds.net