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 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:

  • 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

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}

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.