GETTING STARTED

Jama Rest API

Getting Started

API Policies

Announcements and Recent API Changes

Important Links

Getting Started

Availability

The REST API is available in our hosted SaaS instance Jamacloud and for on-premises customers running 8.0 or above.

Getting Access

REST is enabled by default for Cloud customers.

On-premises customers can enable REST via system administration.

SOAP is not available for any supported version of the service.

Using Swagger UI

Swagger UI is an interactive documentation tool used with REST API. This tool is available to users with a valid login and REST enabled. Swagger can be accessed through {Context-Path}/api-docs/

If you are not logged in, the login page will display and then take you to Swagger: If your instance of Jama does not have REST enabled you will receive this message:

“Can't read swagger JSON from {Context-Path}/rest/latest/api-docs”

A list of resources will be displayed and you can explore all of the supported endpoints.

Resource List

Each endpoint will detail its parameters, request object, and response object, as well as which parameters are required.

Endpoint screenshot

Fill out the desired parameters and forms and click “Try it out!” A response will be returned from the server, along with the formatted URL:

Try it out

To quickly obtain the schema for a request object, click Model Schema and click on the formatted JSON in the window. A sample model will be loaded in the Body window to the left and the JSON can now be edited:

Schema

Advanced Authentication (OAuth)

Basic Authentication

Most rest clients have an easy interface for basic authentication. You must provide your username and password in the header of the request following the RFC 2617 standard

Note: This type of authentication will not work in a SAML/SSO environment.

Examples for username: “myusername” and password: “mypassword”

Header
Authorization: Basic somestringoftext

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

OAuth

Jamacloud users and self hosted users starting with 8.62 can authenticate REST calls via OAuth.

Getting Ready

To use OAuth as your method of authentication with the Jama application, you will need the following:

A client application that supports OAuth, specifically the client credentials “flow” or “grant type”. This means that your client application will take a client ID and client secret
Client credentials, specifically a client ID and client secret. You can create these credentials via the Jama UI, by following these steps from your User Profile page:
1. Click the “Set API Credentials” button:
2. Enter a name for your application/integration:
3. Click the “Create API Credentials” button:

Be sure to copy your Client ID and Secret. The secret is only displayed once!

Legs

The client credentials flow as implemented by the Jama OAuth service has the following two legs:

Exchange client credentials for an access token (once)
Make request to the REST API using the access token (repeatedly)

Repeat when the access token expires. (The Jama OAuth service does at this time not support refresh tokens. You will have to observe the expiration time that is returned when exchanging client credentials for an access token. The duration that your access token is valid may be different between Jama servers.)

Exchange Client Credentials

The goal of this leg is to exchange client credentials (specifically a client ID and client secret) for an access token.

Make a request as follows:

Request: POST
Target: /rest/oauth/token on your instance of the Jama application, e.g.: https://xyz.jamacloud.com/rest/oauth/token
Please Note, there is no training slash ‘/’ after token
Data: grant_type=client_credentials
Authentication: HTTP Basic Authentication with client ID as user name, client secret as password

If your connection library does not support HTTP Basic Authentication, you may consider adding an additional header:

Name: "Authorization", value: “Basic AUTHORIZATION“, where AUTHORIZATION is a Base64-encoded presentation of “ID:SECRET“, where ID is the client ID and SECRET is the client secret

This will return a response that includes a access_token field, which is the access token used for the next leg. It also includes an expires_in field, which is the number of seconds until the access token expires (1 hour is the default). The access token can be used many times until it expires.

Here is an example using curl for a client ID test123:

$ curl --request POST http://test123:EC231BA29695BF2CBAB6@basepath/rest/oauth/token \
	--data grant_type=client_credentials \ {
"access_token":"eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NDQ5MjI4OTcsInNjb3BlIjpbInJlYWQiXSwianRpIjoiNTQ3N2... (et cetera)",
"token_type":"bearer",
"expires_in":3599,
"scope":"token_information",
"application_data":{
"JAMA_CORE":"sample"
},
"tenant":"default",
"jti":"d480b154-4e5e-446b-beec-2f1b7cdc0e35"
}

REST API Request

The goal of this leg is to make a request to the REST API using the access token from the previous leg.

Make a normal request to the REST API, except instead of HTTP Basic Authentication, add an additional header:

Name: Authorization, value “Bearer AUTHORIZATION“, where AUTHORIZATION is the access_token from the previous leg

This will return a normal response from the REST API.

Here is an example using curl to make a request to the /users REST API endpoint:

$ curl --request GET http://basepath/rest/v1/users/current
       --header "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NDQ5MjI4OTcsInNjb3BlIjpbInJlYWQiXSwianRpIjoiNTQ3N2... (et cetera)" {
"meta":{
"status":"OK",
"timestamp":"2015-10-28T22:33:16.524+0000"
},
"links":{},
"data":{
"id":5,
"username":"sample",
"firstName":"Sample",
"lastName":"User",
"email":"admin@my.domain.com",
"phone":"",
"title":"",
"location":"",
"licenseType":"NAMED",
"active":true,
"type":"users"
}
}

Versioning

Change is inevitable. Versioning is used to ensure integrations can be protected and updates managed. For these reasons, Jama recommends stating the REST version in all requests. Jama has multiple version endpoints.

v0 – Pre-beta version, Removed in 8.22 but may be in use by Self Hosted clients using unsupported versions of Jama Connect
v1 – Current supported version of REST.
latest – Designated for Sunset- See Sunset details
labs – Version introduces new endpoints for feedback without breaking or confusing supported versions. This version will not be officially supported and endpoints may change or be removed in future releases.

To access documentation for the different versions, update the swagger URL.

The Jama REST API is versioned separately from the Jama product releases. Multiple API versions are supported in each Jama release in order to provide backwards compatibility.

To query which API versions are available issue a request like the following:

GET https://xyz.jamacloud.com/rest

API Sunset EOL policy

When Jama has a new version of the API completed we will release the new version and begin Sunset activities. Versions are viewed as full points (eg. v2, v3, .. v10).

Each sunset/EOL timeline will be unique, based on the complexity of change.

Sunset/End-of-Life (EOL) process is presented below.

Jama will NOT release more than one full point version per calendar year
Jama Connect On-Premise users: Sunset window will never be smaller than one Standard release..
Jama will continue to innovate and correct the API within the scope of the Breaking Changes Definition

Impact:
Clients who have implemented code connectivity to the Jama Rest API will need to review and modify connections to utilize the new Rest API version and schema. Failing to do so will result in broken connectivity and errors when the Sunset EOL is complete.

Sunset and Support Timeline:

- Cloud Jama instances will gain access to the new API version during a regular monthly release.
- On-premise Jama instances will gain access to the new API version during the next Standard Release

Sunset/EOL timing begins from the date of Cloud Availability.
- On-Premise Jama clients are encouraged to review available documentation and migration information to begin planning in advance of schema availability.

New version information will be announced via a combination of:

Jama Connect release notes
Notation in Swagger and within Jama Response Headers
http://community.jamasoftware.com
http://dev.jamasoftware.com
Jama will engage email notifications halfway through the sunset period with increasing frequency as the removal date gets closer.
Jama Account Managers may also increase in communication frequency as timing diminishes.

Definition of API Breaking Change

Jama will continue to innovate and change REST API methodologies with the intent to:

Increase efficiency
Improve developer usability
Remove monolithic perspectives

Breaking Changes will be defined as:

“Any modification in which Lock-step Client/User/Integration modification is required in order for the consuming code to continue to work properly. Breaking changes may not always be code based, and will include data intent.”

In some cases, a Breaking change cannot be avoided (ie to resolve unintended bug behavior) Jama will alert appropriately when this occurs via several distribution channels.

Jama Encourages Integrator and users of our API to share deep details of usage with us so that we can include fringe scenarios in our Breaking Change review processes. Breaking Changes may be delay released for inclusion in an overarching version increase. This will occur to minimize sunset and migration impact on users.

Jama will utilize the “/labs” REST endpoint to test bed solutions that may never be included in production REST endpoints
Modifications to any data in the “/labs” endpoint will never be considered Breaking Changes

Breaking Change examples:

Changing or Removing/Deleting a method or resource name
Addition of Required parameters for any endpoint.
Addition of Optional parameters that will modify the Default response behavior
Modification of data Nesting structure in the JSON responses
Implementation of or changes to Caching Strategies that impact delivery
Increase in default response datatype size limits (Example: Changing text/Blob/Clob)

Non Breaking changes will typically manifest as:

New Optional parameter where the default behavior is not impacted
New resource or API endpoint (Net New)
New optional key in the JSON POST
New key is returned in the JSON response

Limited Break Perspective:
Jama will refrain from changing the intent of an HTTP Response Code in production. Developers may have built parsing behaviors around certain response text, even when it may result in unsustainable results.
Changes correcting nonconforming language or behavior are not considered breaking changes

Error 500 being corrected to resolve to a 400 via better error handling
Response code language changes are not considered breaking changes

Common Response Codes

200 – OK
The request was processed successfully. This code gets returned after GET requests or PUT requests (if the PUT resulted in data being generated and returned).

201 – Created
The POST request was processed successfully.

204 – No Content
The DELETE request was processed successfully.

400 – Bad Request
The request could not be parsed or the parameters were not valid. The request should be modified before resubmitting.

401 – Unauthorized
Username/password is invalid or the user does not have access to the requested object.

404 – Not Found
Syntax is correct on the request, but does not exist at the location specified.

405 – Method Not Allowed
There is an issue with the way the request was made.

429 – Too many requests
Only returned for API throttling or system maintenance.

Announcements and Recent API changes

Current Sunset Activity

2019-11-22 – ‘/latest’ API Endpoint Sunset announcement
EOL = 2020-05-22
See community post for more details

API Change Log

2024/05/30 — Version: Jama Connect 9.12

Category resources and endpoints have been moved into v1.

GET /categories
POST /categories
PUT /categories/{categoryPathId}/visibility
GET /items/{itemId}/categories
POST /items/{itemId}/categories

2023/09/23 — Version: Jama Connect 9.4

REST API is now restricted to users with creator licenses.

You can now create, read, and update info tips for field labels in picklists

GET /picklistoptions/{picklistOptionId}
PUT /picklistoptions/{picklistOptionId}
POST /picklists/{picklistId}/options

You can now create and read info tips for picklist values in fields for item types

GET /itemtypes/{itemTypeId}
POST /itemtypes/{itemTypeId}/fields

2023/08/04 — Version: Jama Connect 9.2

GET /relationships performance updates – review new options in the API Cookbook.

Manage project permissions with user groups

GET /projects/{projectId}/permissions – Use to read the permission entries for a specified [user or user group] for a specified [project or folder of projects]
POST /projects/{projectId}/permissions – Use to create or override permission entry for a specified [user or user group] to a specified [project or folder of projects]
PUT /projects/{projectId}/permissions – Use to update existing permission entry for a specified [user or user group] to a specified [project or folder of projects]
DELETE /projects/{projectId}/permissions – Use to remove the existing permission entry for a specified [user or user group] to a specified [project or folder of projects]

2023/05/05 — Version: Jama Connect 8.86

The POST /baselines labs endpoint now allows you to create a baseline without having to first create a source.

2023/01/06 — Version: Jama Connect 8.82

Newly introduced endpoint GET items/{id}/versioncategories parameter option has changed from versionID to versionNumber to match existing patterns

2022/11/11 — Version: Jama Connect 8.80

Items in the baseline will include the category applied at time of the baseline
GET baselines/{baselineId}/versioneditems now contains the applied category snapshots at the time of the baseline

2022/10/14 — Version: Jama Connect 8.79

Categories updates – within Labs
GET /categories retrieve all category paths by name (and/or) project id
POST /categories create a new CategoryPath
PUT /categories/{categoryPathId}/visibility updates category visibility

New report endpoint – within Labs
POST /reports/{reportId} Create a new report as an asynchronous request (a successful response signifies that the work was started and a work identifier is given. This identifier will be used in a future feature)
GET /reports/metadata get all Reports Metadata for a given project

2022/06/24 — Version: Jama Connect 8.75

Picklist details include standard vs. lookup_matrix
POST /picklist includes the option for STANDARD and LOOKUP_MATRIX
GET /pick list endpoint now returns STANDARD and LOOKUP_MATRIX

2022/05/27 — Version: Jama Connect 8.74

PATCH /items
Update an array of items with the specified ID as an asynchronous request.

PUT /items/{treeLocation}
Set item location by indicating parent and location of peer.

Baseline updates
GET /baselines endpoint now returns the baseline pick list option
GET /baselines/ {baselineId} endpoint now returns the baseline pick list option
PUT /baselines/ {baselineId} endpoint now can update the baseline pick list option

2022/04/01 — Version: Jama Connect 8.72

GET /baselines/{baselineId}/reviewlink
Review ID of the baseline

New baseline options added to labs
POST /baselines
GET /baselines/folders
POST /baselines/folders

2022/02/04 — Version: Jama Connect 8.70

Move a baseline source to a folder
PUT /baselinetree/{projectId}/move

2021/12/10 — Version: Jama Connect 8.68

GET /filters/{filterId}/count
New endpoint to provide the filter result count without returning items within a filter.

Additional option for user
New multi-auth option allowing for SAML and Basic Auth to be used together. When enabled, the creation of users with REST will need to specify the authentication type. Those specifying Basic will be required to include a password.
name:“Basic”, id:1
name:“IdP”, id:2

Removal of resource revision item from documentation. The internal resource was included in the documentation in error.

Labs support applying and removing new categories via GET and POST /items/{itemId}/categories

2021/06/04 — Version: Jama Connect 8.62

PUT/PATCH updates for testruns
Custom fields are now updateable. To match the recent UI update, custom fields can now be updated via the API. The update continues to mirror UI behavior for updating test runs. Only the fields editable from the execution UI can be updated. Previously the inclusion of custom fields in an update was treated as read-only fields and ignored.

Labs include POST for baselines.

2021/04/23 — Version: Jama Connect 8.61

Additional permissions for GET/users and GET/usergroups
Access to GET/users and GET/usergroups will require organization or user admin roles. Project admins can continue to use these endpoints but will be required to provide a project ID where they are project admins.

Access to GET/users/{userId} & GET/usergroups/{id} will now perform a permissions check ensuring the requesting user has access to the same project as the requested user or user group.

2021/02/12 — Version: Jama Connect 8.59

New API Header: x-jama-date-fields-with-time
New header option to provide full ISO-8601 formatting of dates within the fields section.

Legacy Soap service (Unsupported)

The Jama Soap service has been replaced by our REST api. A handful of Self-Hosted organizations are using unsupported Soap-based revisions of Jama Connect, such as the 2015 Spring release.

Due to requests from the community, we have restored minimal unsupported documentation for the Soap service. Development and Admin teams are encouraged to open conversations with Jama to begin redeployment projects to a newer version of Jama Connect. Internal information will continue to become sparse as we get further from the supported timeframe for the Soap service.

Timeline:

June 1^st, 2016 – SOAP Sunset announced
December 31^st, 2016 – SOAP full support ended
June 30^th, 2017 – Release of Connect v8.20 removes SOAP API
June 30^th, 2017 – Best effort support ended
January 2019 – Documentation removed from
May 2019 – Minimal documentation restored to the following location (Soap service – Spring 2015 version)
May 2020 – Restored Soap service documentation will be removed permanently from the Jama site.