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 Hosted users 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
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.
2020/09/25 — Version: Jama Connect 8.55
New API Endpoint: /activities/adminActivity Retrieve new Administration Activities. Addition of username to Activity response.
2020/01/03 — Version: Jama Connect 8.45
New API Endpoints: Disclose sets of Relationship Rules We have added the ability for API GET requests to supply Relationship Rule Sets to assist with integration processes.
2019/11/22 — Version: Jama Connect 8.44
Velocity API changs to Proxied version (Velocity documentation)
Announcement of '/latest' REST endpoint sunset - See Current Sunsets above.
2019/10/18 — Version: Jama Connect 8.43
Updated default Swagger endpoint from 'latest' to 'v1'. users can still gain access to 'latest' as needed, though named versions is a safer alternative.
Resolved issue SOS-DEF-2748 - "GET /filters for project no longer returns private filters for currently authenticated user". Default restored to return both public and private. Added an API parameter limit to either public or private.
2019/09/23 — Version: Jama Connect 8.42
Internal improvements, no external modification needed.
2019/08/27 — Version: Jama Connect 8.41
Resolved issues with Swagger sort order, result retuned to Alpha sort.
Resolved issues blocking Swagger from working behind a Reverse Proxy.
2019/08/03 — Version: Jama Connect 8.40
Resolved issues - SOS-DEF-318, SOS-DEF-2313, SOS-DEF-3992 - Custom URL fields are to rigid and improperly block valid URLs from being applied to an item. (UXI and API).
2019/06/28 — Version: Jama Connect 8.39
REST API: Improved batch delete restoration
When performing batch deletes, the previous restoration process required "all or nothing" restorations. With the improved API, you can restore individual child items without having to restore the entire batch deletion.
Note: Restoration of a child item will necessarily restore its parent container. Also, this restore does not block future restoration of other child items.
---
Resolved issue - SOS-DEF-4258 User is unable to move a set to the root of the project via API.
2019/05/31 — Version: Jama Connect 8.38
Calls merged from LABS end point to v1 sustain production:
Get/Activities * COPY * MOVE * BATCH_CREATE * BATCH_UPDATE * BATCH_DELETE * BATCH_COPY Adds: data.itemType and related object data POST /itemtypes/ POST /itemtypes/{itemTypeId}/fields POST /picklists DELETE /picklists/{picklistId} POST /projects/{projectId}/itemtypes/{itemTypeId} DELETE /projects/{projectId}/itemtypes/{itemTypeId}
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: