Jama Rest API

Overview

The Jama REST API has been designed to provide developers with a clean and straightforward experience for integrating with Jama. If you haven’t already, we encourage you to spend a little time getting acquainted with the Jama administration area as this will help you understand the language and configuration options that drove the design of the REST architecture.

For discussion and additional examples please visit our community. Support is limited to providing insight into which API calls might be useful. It is not in scope to write code snippets or provide training.

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 not enabled by default.

SaaS customers will need to send a request to support via the portal http://support.jamasoftware.com or email support@jamasoftware.com.

On-premises customers can enable REST via system administration.

Using Swagger

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

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 of REST that was completely removed with the release of 8.22.
• v1 – Current supported version of REST.
• latest – Default swagger option that pulls newest version of REST.
• 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.

Authentication

$ 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"
}
						

 
$ 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"
}
}

Release Updates

3/25/2017 - 8.14

Test Runs include the version of the test case it was created from and the current version of the test case.

Testruns returned with group order within cycle.

Each testrun indicates its sort order within the test group it belonged to when the test cycle was created or edited.

Test Cycles include version endpoints.

New options to retrieve testrun.

Query Params:

• testPlan=(id of testplan)
    - Muliple test plans allowed. This group is OR together
• testCycle=(id of testcycle)
    - Multiple test cycles allowed. This group is OR together
• testCase=(id of testCase)
    - Multiple test cases allowed This group is OR together
• The different types of query params are always AND together.
  e.g. (TP1 || TP2 || TP3 || ....) && (TC1 || TC2 || TC3 || ....) && (TCy1 || TCy2 || TCy3 || ....)
• If the ID does not match the type, it does not error. ID will not make any matches. If no testPlan, TestCycle, or testCase is provided, return 0 results.
 

Defect Fix: Querying /activities/?objectType=TEST_CYCLE, TEST_RUN, TEST_CASE, or TEST_RESULT returns no items.

Defect Fix: Retrieving non-Explorer tree content via abstractitems endpoint may not return all items as indicated by the total results.

2/25/2017 - 8.13 (HOSTED)

Edit Read Only Fields

A new option is available with the item type field configuration allows for non-system read only fields to be editable via the REST API. This option is targeted at integrations that need data represented in Jama, but not editable by a user. An example would be a JIRA URL for a synced item.

Location on Baselines versioneditems

When a baseline is created, the system records the location of the included items as part of the baseline and is now available via REST. The location data is important for anyone attempting to recreate a document or archive this data in the same order as it was originally reviewed. Please note this information is not available on all versionitems as the location is only preserved when a baseline is created.

get /baselines/{baselineId}/versioneditems

1/27/2017

Two new efficiency options:

• include parameter
  This parameter provides the ability to pull the content from linked objects to reduce the number of requests needed to retrieve information.
• PATCH
  PATCH allows for partial updates to items, testcycles, testplans, and testruns resources.

And the first option to help with administration. Picklist options can now be managed via:

• post /picklists/{picklistId}/options
• put /picklistoptions/{picklistOptionId}

4/15/2016

REST out of Beta and available to on-premises customers using 8.0 or above.

All customers running 8.0 or above of Jama has access and support to REST.

Hosted 2/20/2016

The new group resource provides the ability to retrieve all groups in the system, determine membership and include/exclude users. User provisioning is now possible by combining Groups with the existing user resource.

Hosted 1/23/2016

Two new resources available.

• Baselines - Retrieve all baselines within a project, the details about each baseline and the versioned items that make up each baseline.
• Releases - Manage a project’s release values.

Three new endpoints for retrieving an item’s version description and details. Attachments, testplans and testruns also include these new endpoints.

• get /items/{id}/versions
  retrieve list of version description/metadata for an item
• get /items/{id}/versions/{versionNum}
  retrieve the specified version description/metadata for an item
• get /items/{id}/versions/{versionNum}/versioneditem
  retrieve the specified item version

And finally, a documentKey specific parameter available on abstractitems that provides the ability to retrieve an item or list of items by the user known identifier, documentKey.

• get /abstractitems?documentKey={documentKey}

Hosted 12/12/2015

Swagger upgraded to version 2. This is the documentation engine behind Jama's api-docs.

Two new endpoints added that provide ability to move collections between projects.

• get /items/{id}/location
  Get the location for the item with the specified ID
• put /items/{id}/location
  Update the location for the item with the specified ID 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). Any child items are moved along with this item. Note that this currently only supports moving items between projects.

Include Parameter

This parameter provides the ability to pull the content from linked objects to reduce the number of requests needed to retrieve information. For a great overview in how our design came about and the thoughts that went into to it please read http://www.jamasoftware.com/blog/rest-api-design/.

Example Request:

curl -X GET --header "Accept: application/json"
"https://www.jamaland.com/rest/latest/items/2737149?include=data.fields.priority&include=data.project"
						

The response includes a new linked section:

"linked": {
"projects": {
"24114": {
"id": 24114,
"projectKey": "API",
"isFolder": false,
"createdDate": "2014-06-05T11:12:01.000+0000",
"modifiedDate": "2016-01-19T19:28:57.000+0000",
"createdBy": 22374,
"modifiedBy": 21798,
"fields": {
"projectManager": 21798,
"user1": 22374,
"projectKey": "API",
"statusId": 178902,
"text1": "",
"name": "REST API",
"description": "",
"projectGroup": 178905
},
"type": "projects"
}
},
"picklistoptions": {
"178888": {
"id": 178888,
"name": "High",
"description": "",
"value": "5",
"active": true,
"color": "9CE78C",
"sortOrder": 4,
"pickList": 102546,
"default": false,
"type": "picklistoptions"
}
}
},

PATCH

The PATCH http verb is available for items, testcycles, testplans, and testruns resources.

PATCH allows for partial updates of REST resources. You do not have to have the entire object (e.g. Request Item required for PUT) to make an update. A list of Request Operations is used to transform the current version of the object.

JSON Payload: Request Patch Operation

For PATCH /items/id, you will provide a list of changes you want to make. This is based off of RFC 6902. Currently we support add, replace, and remove.

This operation sets the value to the field in the path. The field at the path must exist. Value is required.

{
"op": "replace",
"path": "/fields/name",
"value": "New Updated Name"
}

This operation clears the value of the field in the path. The field at the path must exist. Value does not need to be set.

{
"op": "remove"
"path": "/fields/description"
}

This operation sets the value to the field in the path. If the field does not exist at the path, it is added. Value is required.

{
"op": "add"
"path": "/fields/customField$12",
"value" : "Hello!"
}

Notes

• Paths always reference what you would expect to see in a request object JSON payload for the PUT endpoint of the resource you are working with. This means you must provide the $ suffix on custom field names (see the "add" operation above).
• Expect new 400 errors.
  • "no such path in target JSON document" - Check that the path is possible on the Request Object for the resource. A field will not show up in the request object if it is currently null.
  • "The value you provided could not be set at the path." - Check that the value matches the type at the path. i.e. Are you trying to set an integer to a string field?
• Remove will ensure that the attribute in the path is cleared. A valid path must be provided.
• You may provide JSON objects with nested values as the 'value' of a Request Patch Operation. For example, you may replace an items location with a whole Request Location.

"value": { "parent": { "item": 99 } }

Paginated Lists

The API provides strict pagination to reduce load on the application.

• startIndex - Integer that describes the current response’s offset into the list of all results.
• resultCount - Integer that describes the max number of items returned per page. The default response is 20 items, however an upper limit of 50 can be provided.
• totalResults - Integer that descrives total amount of items available in list.

Date Format

The Date format used is based on the ISO 8601 standard, but has additional restrictions. The time field and the timezone must be included. For example, July 1st 2015, 11 AM in GMT would be written as 2015-07-01T11:00:00.000+0000. Note that the UTC offset is required, because Jama uses UTC time to avoid ambiguity. In this case the offset is +0000 for GMT. Jama will always respond with the +0000 offset.

Examples

Note that date fields on items do not have time granularity. You will use yyyy-MM-dd format for these. E.g. 2015-09-05 for September 5th 2015.

Sample Response

Jama is extremely configurable by business users. At any time, an Organization Admin may choose to create, modify or remove an item type, which if you are not familiar, you can think of as an artifact. This means that Jama needs to provide developers with the ability to discover the available item types and the types of fields used, including pick list values. Any integration that hard codes these should expect surprises when the business decides they want a change several labels, add a new field or remove a pick list value.

Meta

The meta section provides an overview of the response and, when returning a list, the size of the list and the location within the pagination.

{
"meta": {
"status": "OK",
"timestamp": "2015-09-10T23:05:53.856+0000",
"pageInfo": {
"startIndex": 0,
"resultCount": 20,
"totalResults": 37
}
},

Links

The links section was designed to serve two purposes. First was to make the Jama content and configuration discoverable. Links are provided for easy retrieval of valid pick list values, item type description, related items, users or project. The second purpose of the design is to manage the size of the response and remove duplicate information. Some item types can have upwards of 50 fields and returning all content around a status pick list in each item would not be efficient.

"links": {
"data.location.parent.item": {
"type": "items",
"href": "http://localhost:8080/jama/rest/latest/items/{data.location.parent.item}"
},
"data.modifiedBy": {
"type": "users",
"href": "http://localhost:8080/jama/rest/latest/users/{data.modifiedBy}"
},
"data.project": {
"type": "projects",
"href": "http://localhost:8080/jama/rest/latest/projects/{data.project}"
},
"data.createdBy": {
"type": "users",
"href": "http://localhost:8080/jama/rest/latest/users/{data.createdBy}"
},
"data.fields.priority": {
"type": "picklistoptions",
"href": "http://localhost:8080/jama/rest/latest/picklistoptions/{data.fields.priority}"
},
"data.fields.release": {
"type": "release",
"href": "http://localhost:8080/jama/rest/latest/release/{data.fields.release}"
},
"data.fields.status": {
"type": "picklistoptions",
"href": "http://localhost:8080/jama/rest/latest/picklistoptions/{data.fields.status}"
},
"data.itemType": {
"type": "itemtypes",
"href": "http://localhost:8080/jama/rest/latest/itemtypes/{data.itemType}"
}
},

Data

The data section is broken up into two areas. The top area consists of the data that the system includes on every item within Jama. The “fields” section matches the fields configured on an item type and will match the content visible in the UI. Fields may be in both areas as an admin can opt to show system fields, such as createdBy, in an item’s detail view.

Note the “status”: value of 293 and be plugged into the above link to retrieve the details. http://localhost:8080/jama/rest/latest/picklistoptions/293

"data": {
"id": 25,
"documentKey": "CP-REQ-5",
"globalId": "GID-25",
"itemType": 24,
"project": 1,
"createdDate": "2014-09-09T03:32:21.000+0000",
"modifiedDate": "2014-10-16T03:44:30.000+0000",
"lastActivityDate": "2014-10-16T03:44:30.000+0000",
"createdBy": 5,
"modifiedBy": 5,
"fields": {
"documentKey": "CP-REQ-5",
"globalId": "GID-25",
"name": "Uploading of Patient Records",
"description": "<p style=\"margin:0pt\"><span>Patients that agree to be managed ...</span></p>",
"priority": 301,
"status": 293,
"release": 2
}
},

Resources

The resources section provides a list of the available actions for the authenticated user. In the example below, the user that made this request can opt to read, update or delete the item.

"resources": {
"self": {
"allowed": [
"GET",
"PUT",
"DELETE"
]
}
},

Location

The location section is designed to present the data about an items location with a project’s explorer tree. These values are derived by the system and on the parent can be controlled via the REST API. This means that the specific order within a tree node cannot be set. Updating an item’s parent will place it at the bottom of that parent’s list of children items.

"location": {
"sortOrder": 1,
"globalSortOrder": 4063,
"sequence": "2.1.7.1.2",
"parent": {
"item": 23
}
},

Lock

The lock section handles the different locks that can be applied within Jama. A user may lock an item by editing an item, opting to lock an item for themselves or changing a workflow state that results in a locked item.

"lock": {
"locked": false,
"lastLockedDate": "2012-11-16T04:44:30.000+0000"
},
"type": "items"
}

Sample Header

Note that Jama only supports JSON but the Content-Type value is required

PUT /jama/rest/v1/items/23 HTTP/1.1
Host: localhost:8080
Authorization: Basic c2FtcGxlOnBhc3N3b3Jk
Content-Type: application/json
Cache-Control: no-cache

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.

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

Throttling

Jama’s SaaS environment "jamacloud" throttles API requests for REST and SOAP. The application servers have a maximum number of threads available for responding to API requests to prevent the system from being overwhelmed by aggressive integrations. Requests will be queued and the system will respond with a 429 when the queue is full or requests within the queue have timed out.

Jama will monitor API usage as integrations are built and continue to refine throttling and usage agreements as we gather information around usage.