Cursor Tutorial

This tutorial describes details on pagination with Cursor objects

Introduction

We use pagination a lot in Wikirate API development. Iterating through companies, metrics, answers, relationship answers, sources, topics, projects etc. In order to perform pagination, we must supply an offset and a limit parameters with each of our requests. This requires a lot of boiler plate code just to manage the pagination loop. To facilitate iteration and require less code, wikirate4py provides the Cursor object.

How to use

Cursor handles all the iteration/pagination work for us behind the scenes, thus our code can focus entirely on processing the results.

api = wikirate4py.API('you_api_token')

# create Cursor object that iterates the results (results per page = 100, default value = 20)
cursor = wikirate4py.Cursor(api.get_metrics)

while cursor.has_next():
    # next method returns a list of Metric objects
    results = cursor.next()
    # do something more to process your results

Passing parameters

What if you need to pass parameters to an API method that supports iteration?

api.get_answers(metric_name='Company Report Available',
                metric_designer='Core',
                country='United Kingdom',
                year=2019)

Since we pass Cursor the callable, we can not pass the parameters directly into the method. Instead we pass the parameters into the Cursor constructor method as demonstrated below:

api = wikirate4py.API('you_api_token')

# create Cursor object that iterates the results (results per page = 100, default value = 20)
cursor = wikirate4py.Cursor(api.get_answers,
                            metric_name='Company Report Available',
                            metric_designer='Core',
                            country='United Kingdom',
                            year=2019)
while cursor.has_next():
    # next method returns a list of Metric objects
    results = cursor.next()
    # do something more to process your results

Limits

By default, Wikirate allows 20 items per page, however users can request from Wikirate’s API to return more items in one go. If you would like to request more items in one go using the Cursor then you need to define an additional parameter called per_page.

cursor = wikirate4py.Cursor(api.get_metrics, per_page=50)

while cursor.has_next():
    # next method returns a list of Metric objects
    results = cursor.next()
    # do something more to process your results

Note that, wikirate4py allows max 100 items per page. If you define per_page>100 then the Cursor by default will set per_page=100.