Getting Started

Jama Rest API

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.

Endpoints

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 bXl1c2VybmFtZTpteXBhc3N3b3Jk

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:

  1. Exchange client credentials for an access token (once)
  2. 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 an 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.

Versioning


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

Jama Software : 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 point (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 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 combination of:

  • Jama Connect release notes
  • Notation in Swagger and with-in 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.

Jama Software : Definition of API Breaking Change


Jama will continue to innovate and change REST API methodologies with an 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 which will modify the Default response behavior
  • Modification of data Nesting structure in the JSON responses
  • Implementation of or changes to Caching Strategies which 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 default behavior is not impacted
  • New resource or API endpoint (Net New)
  • New optional key in the JSON POST
  • New key 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 with more details

API Change Log

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 baseline will include category applied at time of 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 retrieves 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 arrary 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 mulit-auth option allowing for SAML and Basic Auth to be used together. When enabled, creation of users with REST will need to specify authentication type. Those specifying Basic will be required to include a passowrd.
name:“Basic”, id:1
name:“IdP”, id:2

Removal of resource revisionitem from documentation. Internal resource was included in documentation in error.

Labs supports 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 field in an update were treated as read only fields and ignored.

Labs includes 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 a project admin.

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 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 1st, 2016 - SOAP Sunset announced
  • December 31st, 2016 - SOAP full support ended
  • June 30th, 2017 - Release of Connect v8.20 removes SOAP API
  • June 30th, 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.