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.
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
) to simplify the example. Import json
as well, so that you can easily access the results of the requests you’ll be making.
Set aside some strings that you’ll use later in your request, and 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)
, mirror the names of the values in the “pageInfo” object.
is your loop control, and
is your current position in the results paging. The
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
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:
If the Jama REST API receives a startAt=
parameter which is greater than or equal to
, it sends back a “resultCount” value of zero. When that happens, you know you’ve consumed all the results which match your request.#REST