Getting Started
The REST API is available in our hosted SaaS instance Jamacloud and for on-premises customers running 8.0 or above.
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.
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.
Each endpoint will detail its parameters, request object, and response object, as well as which parameters are required.
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:
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:
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
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:
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:
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:
POST
/rest/oauth/token
on your instance of the Jama application, e.g.: https://xyz.jamacloud.com/rest/oauth/tokengrant_type=client_credentials
If your connection library does not support HTTP Basic Authentication, you may consider adding an additional header:
"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 secretThis 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:
access_token
from the previous legThis 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" } }
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.
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:
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.
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:
New version information will be announced via combination of:
Jama will continue to innovate and change REST API methodologies with an
intent to:
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.
Breaking Change examples:
Non Breaking changes will typically manifest as:
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
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.
2019-11-22 - '/latest' API Endpoint Sunset announcement EOL = 2020-05-22 See community post with more details
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
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.
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: