Knowledge Base

Overview
The Jama REST API uses pagination when returning multiple results.  This means that if you request all the items in a project you will get the first 20.  Pagination is a standard way of delivering manageable results and ensuring performant requests.  The obvious next question is: “How do I get the rest of the results?”

Before you begin
This example assumes basic familiarity with Jama’s REST API and making REST calls.

Background
In the “meta” object of every collection response is an object called “pageInfo”.

This object contains all the information you need to move through the rest of the data you’re looking for.
• “startIndex” is the index of the first result.
• “resultCount” is the number of results retrieved in this request.
• “totalResults” is the total number of values that this request matches.

Using these three values, you can consume the rest of the results.  

Example
List the names of all of your projects using Python and the Requests library.  
This example omits any error checking.

First, import the Requests library (http://www.python-requests.org) to simplify the example.  Import json as well, so you can easily access the results of the requests you’ll be making.  

import requests  
import json  

Set aside some strings that you’ll use later in your request.  Separate the base URL from the name of the resource so you can reuse the base URL elsewhere in code.  It’s also a good idea to store your API_User’s password somewhere other than the source code.

base_url = "https//Context-Path/rest/latest/"  
username = "API_User"  
password = **********  
resource = "projects"  

Next, establish how many results you’ll accept from the Jama REST API with each request. You’ll need the int to advance through pages of results and the string to send as a parameter to the GET request.  For this example limit the results to 10. 

allowed_results = 10  
max_results = "maxResults=" + str(allowed_results)  

The variables result_count and start_index mirror the names of the values in the “pageInfo” object.  result_count is your loop control, and start_index is your current position in the results paging.  The start_at string is a parameter to your GET request which allows you to start your results at any index.

result_count = -1  
start_index = 0  
   
while result_count != 0:  
    start_at = "startAt=" + str(start_index)  

Now, package up the URL you want to hit.  The string you’re constructing will look something like:

The ‘?’ indicates the start of a list of parameters which are separated by the ‘&’.

Make the GET request and load the results as json.

    url = base_url + resource + "?" + start_at + "&" + max_results  
    response = requests.get(url, auth=(username, password))  
    json_response = json.loads(response.text)  

Pull out the “pageInfo” object so you can update your start_index and result_count variables.

    page_info = json_response["meta"]["pageInfo"]  
    start_index = page_info["startIndex"] + allowed_results  
    result_count = page_info["resultCount"]  

Now you can get down to business.  Iterate over all the returned projects and display their names.

    projects = json_response["data"]  
    for project in projects:  
        print project["fields"]["name"]  

If the Jama REST API receives a startAt= parameter which is greater than or equal to total_results it sends back a “resultCount” value of zero.  When that happens, you know you’ve consumed all the results which match your request.

#REST