Sample API calls to Jama Connect®

Radjesh
Radjesh
  • Updated

Author: Radjesh Ramautar

Date: July 24, 2024

Audience: Creator Users: Software Developers, System Engineers

Products Applicable: Jama Connect®

Use Case

The Jama Connect REST API allows for a multitude of integrations that can enhance various business processes, such as:

  • Integrating Test Results: Connect automated test results with the Jama system
  • Data Extraction for Analytics: Extract specific data to be analyzed using Business Intelligence tools.
  • Automation: Automate repetitive batch tasks to save time and reduce manual effort.

Best Practice

The Jama Software REST API offers developers a simple and efficient way to integrate and expand Jama Connect's capabilities. It supports various use cases and is designed to facilitate seamless integrations with the Jama Connect application, ensuring a straightforward process for developers. This guide is meant to show sample calls and standard methods. Below are complete resources are available on how to utilize our REST API

Implementation

Authentication

To interact with the Jama REST API, developers must authenticate using basic authentication methods.

Authentication Methods

Two primary authentication methods for accessing the Jama REST API are Basic Authentication and OAuth.

Basic Authentication

Basic Authentication involves providing a username and password in the request header following the RFC 2617 standard, but this method is unsuitable for SAML/SSO environments.

OAuth Authentication

OAuth Authentication is recommended for users, especially Jamacloud users and those on self-hosted versions starting with 8.62. OAuth requires a Client ID and Secret to generate an access token, which must be used in the request headers.

To generate an OAuth bearer token, follow the step-by-step guide, API - Authentication - Generating an OAuth Bearer Token for Making API Calls.

Endpoints and Features

The API provides various endpoints to interact with different aspects of the Jama Connect system, such as retrieving and modifying data within your Jama instance. Some of the notable endpoints include:

  • Abstract items: Retrieve, search by ID, and get versions.
  • Attachments: Upload and retrieve specific attachments by ID.
  • Items: Get all items in a project, retrieve and update specific items by ID, and manage item versions and attachments.
  • Users: Retrieve user details, update user information, and manage user statuses.
  • Relationships: Get and manage upstream and downstream relationships.

Versioning and Updates

The Jama REST API versioning ensures that integrations remain functional and backward compatible. Multiple API versions are supported simultaneously to provide a smooth transition during updates.

API updates, including new versions and sunset timelines, are communicated clearly to customers to ensure they can adapt their integrations accordingly.

Pagination and Handling Data

Jama provides strict pagination to reduce the application's load, which is crucial to ensuring system performance and stability. This mechanism helps manage the data presented in each API response efficiently.

Pagination Metadata

The meta section of the API response offers an overview detailing the list's size and current position within the pagination. This is essential for effectively navigating through paginated data.

Handling Pagination in Requests

To move through multiple pages of results, one consumes JSON responses to fetch successive pages. This methodology ensures that the data retrieval is systematic and orderly.

Pagination Example in Java

For users employing Java to interact with Jama's API, a detailed example showing the implementation of pagination with JSON is provided. This showcases practical usage and can serve as a guide for developers.

Recommendations for Efficient Pagination

  • Ensure each API request includes a limit on the number of items retrieved to avoid overloading the system.
    Utilize the 'startIndex' and 'resultCount' metadata fields to iterate through pages sequentially.

Searching and Updating Items

The abstractitems endpoint allows users to search for items within Jama, facilitating dynamic filtering and data retrieval.

Developers can update an item's description or other fields using appropriate API calls. For instance, updating an item involves sending a PUT request with the updated data to the relevant endpoint.

Throttling and Performance

The Jama REST API employs throttling techniques to ensure optimal performance and user experience. API requests are throttled when specific thresholds, such as exceeding 10 requests per second or a 100-request queue limit, are reached, temporarily resulting in 429 response codes until the request load decreases.

The code for return/response codes should be handled appropriately. When receiving HTTP 429, the automation must hold it by retrying the action. Jama recommends implementing exponential backoff (i.e., sleeping and retrying) - so it might wait 3 seconds, then 5, then 8, then 13, etc.

Usage and API ID

The API IDs play a crucial role when working with the Jama REST API, as they uniquely identify items within the system. These IDs can be found in the browser URL when viewing specific items or in a list view within the application.

Users should configure the API settings carefully to match the server's capabilities, ensuring smooth operation and preventing performance degradation due to excessive API calls.

REST API TERMS

ID Description
Project ID

Project IDs are unique to Jama Connect. Your administrator sets the default project and sets the keys.

Example: <project key> - <set key> # <SBX-REQ-1 or SBX-TEST-3>

Global ID

Global IDs reference where a requirement or test was reused globally across Jama Connect projects. The Global ID isn’t unique because several copies of an item with the same Global ID might be connected.

Example: GID-1234

API ID

API IDs are an item's database identifier, and developers use them to interact with Jama Connect from the REST API.

In List View, you can locate the API ID as a column or the browser URL for the item you view.

Example: 21374

WHERE TO FIND THE API ID

Find the Project API ID in the URL:

Find the Filter API ID, navigate to the filter in Jama Connect, and look at the URL:

Find Item API IDs:

Find API IDs in List View:

Swagger UI Overview

Swagger UI is an interactive documentation tool for working with REST APIs. It allows users to explore and test API endpoints directly from the documentation interface. This tool is handy for developers as it provides a clear and interactive way to understand the API's capabilities and functionalities.

Accessing Swagger UI in Jama

To access the Swagger UI for Jama's API, users need a valid login and the REST feature enabled in their Jama instance. For cloud customers, REST is enabled by default, while on-premises customers may need to enable it via system administration. Once logged in, users can navigate to a specific URL pattern to access Swagger UI: https://{your_subdomain}.jamacloud.com/api-docs/, where {your_subdomain} is the subdomain of the Jama instance

Features of Swagger UI

Swagger UI provides an interactive list of API endpoints, each detailing its parameters, request object, and response object. Users can fill out the desired parameters and forms and then click "Try it out!" to send a request to the API and see the response in real time. This interactive approach helps developers quickly understand how to use the API and what responses to expect.

Using Swagger UI with Jama

When using Swagger UI with Jama, developers can:

  • Explore all supported endpoints.
  • Obtain schema for request objects by clicking "Model Schema" and viewing a sample model in the Body window.
  • Perform API requests with basic Authentication by providing a username and password in the request header.

Example Usage

A typical example of accessing a resource using Swagger UI is requesting the /projects endpoint. Below is a curl command example for accessing this endpoint using Basic Authentication:

curl -u myusername:mypassword http://basepath/rest/v1/projects

In this example, replace myusername and mypassword with the actual credentials.
This interface facilitates learning and testing API operations, enhancing the development experience by providing immediate feedback and documentation in one place.

Accessing API Documentation in Jama

Access to Jama's API documentation requires navigating to a specific URL structure: https://{your_subdomain}.jamacloud.com/api-docs/, where {your_subdomain} is the particular subdomain of your Jama instance. This allows users to explore all supported endpoints, review parameters, request objects, and response structures.

REST API Methods

Jama Rest API supports the following Request Types: GET, POST, PUT, PATCH.

Response
All API Methods return a response/return code. Any 2xx status code indicates a successful response. 

GET

  • GET is used to request (i.e., retrieve) data from a specified resource (endpoint).
  • It is considered a safe method because it does not alter any data on the server.

Examples Get

  • Retrieving an Item by ID
    A GET request can retrieve a specific item by its ID. Below is an example:

    curl -X GET --header "Accept: application/json" "https://example-subdomain.jamacloud.com/rest/latest/items/{itemID}"

    Replace {itemID} with the actual ID of the item you want to retrieve

  • Retrieving Projects
    You can retrieve all projects using a GET request. The API endpoint for retrieving all projects resembles the following: 

    curl -X GET --header "Accept: application/json" "https://example-subdomain.jamacloud.com/rest/latest/projects"

    Replace {itemID} with the actual ID of the item you want to retrieve

  • Managing Attachments
    Attachments can be managed through several endpoints. For example, to retrieve a specific attachment by ID, you can use:

    curl -X GET --header "Accept: application/json" "https://example-subdomain.jamacloud.com/rest/latest/attachments/{attachmentID}"

    Replace {attachmentID} with the actual ID of the attachment

POST

  • POST is used to submit data to be processed to a specified endpoint.
  • It is commonly used to create new data in Jama.

POST Example

STEP 1

Gather 3 API IDs

Item Type ID

Go to Admin > Item Types, and you’ll see the API IDs for your item types. e.g., for my environment, the “Folder” itemType is: 90865

Project ID & “Parent” ID

For location – you only need to specify the Parent API ID so it knows where to put the folder. The parent would be whatever item is “above” in the tree, e.g., the set where it lives.

So, let’s say I wanted to put a new folder in the Epic set below:

  • The Project API = 36044​
  • The folder itemType API ID = 90865​
  • The child itemType (e.g., what items will be allowed under the folder, is the Epic item type id): 149529​
  • The Location / Parent API ID (this is the Epic set )= 4328335

STEP 2

curl -X POST "https://pm1.jamacloud.com/rest/latest/items" -H "accept: application/json" -H "Content-Type: application/json" -H "jama-csrf-token: fbb04c45-0a33-4247-b97f-fce13643c1a1" -d "{ \"project\": 36044, \"itemType\": 90865, \"childItemType\": 149529, \"location\": { \"parent\": { \"item\": 4328335 } }, \"fields\": { \"name\": \"folder name\", \"description\": \"folder description\" }}"

PUT

  • PUT is used to update or replace a resource
  • If the resource does not exist, PUT can create a new resource with the given data.

Example(s) PUT

  • Working with Test Plans and Test Cases
    To retrieve all test cases associated with a particular test cycle, you can use the following GET request:
curl -X GET --header "Accept: application/json" "https://example-subdomain.jamacloud.com/rest/latest/testplans/{testPlanID}/testcases"

For updating test run fields, a PUT request can be used as follows:

curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -d "{ \"fields\": { \"status\": \"Passed\" } }" "https://example-subdomain.jamacloud.com/rest/latest/testruns/{testRunID}"

Replace {testPlanID} and {testRunID} with the respective IDs5.

PATCH

  • PATCH is used to apply partial updates to a resource.
  • Unlike PUT, PATCH only requires the data that needs to be updated rather than the entire resource.

Example(s) Patch

  • Updating an Item's Description
    If you need to update the description of an item, you can use the PATCH request. The following example demonstrates how to update an item's description:
curl -X PATCH --header "Content-Type: application/json" --header "Accept: application/json" -d "{ \"fields\": { \"description\": \"New description text\" } }" "https://example-subdomain.jamacloud.com/rest/latest/items/{itemID}"

Insert the specific item ID in place of {itemID} to update that particular item’s description

PUT vs. PATCH Overview

PUT and PATCH are HTTP methods for updating resources in REST APIs. Despite their similarities, they have distinct functionalities and use cases.

PUT Method Characteristics
The PUT method is used to update an existing resource or create a new resource if it does not exist. When sending a PUT request, you must provide the full representation of the resource, even if only a few fields have changed. This method replaces the entire resource with the provided data.

PUT Request Example
A typical example of a PUT request involves updating a user's profile. If you want to update the user's email and username, you must send the entire user object, including any unchanged fields, to avoid overwriting them with null values.

PUT /users/1 HTTP/1.1
Host: yourdomain.com
Content-Type: application/json

{
"id": 1,
"username": "new_username",
"email": "new_email@example.com",
"profile_picture": "existing_picture_url"
}

PATCH Method Characteristics
PATCH is used to apply partial updates to a resource. Instead of requiring the complete resource representation, PATCH only mandates the fields that need to be updated. This makes it more efficient for minor, frequent updates.

PATCH Request Example
Using the same user profile scenario, a PATCH request would only include the fields you intend to update, making it more bandwidth-efficient and precise.

PATCH /users/1 HTTP/1.1
Host: yourdomain.com
Content-Type: application/json

{
"email": "new_email@example.com"
}

Comparison and Use Cases

  • Use PUT when you need to update the entire resource or create a resource if it does not exist at the specified URI.
  • Use PATCH when you need to make partial updates to a resource without affecting other fields.

Choosing between PUT and PATCH often depends on the specific requirements of your application:

  • PUT is suitable for scenarios where the entire resource representation needs to be updated or synchronized.
  • PATCH is beneficial when you only need to update certain fields, want to conserve bandwidth, and reduce the risk of unintended data overwrites.

Additional Resources

For developers looking to get started, various resources are available:

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.