API Operations for Causes

Summary

Operation Name: Retrieve a Cause by Cause ID
Relative API Request Path: ~/api/v1/causes/{causeID}
HTTP Verb: GET
Description: Retrieve a single Cause by Cause ID.

Operation Name: Retrieve all Causes
Relative API Request Path: ~/api/v1/causes
HTTP Verb: GET
Description: Retrieve a collection of currently defined Causes.

Retrieve a Cause by Cause ID

Description: This API method retrieves a Cause from the Issuetrak data store for a specified Cause ID. The “causeID” parameter must correspond to an existing Cause. If there is no such Cause ID, an error message will be returned with an HTTP response status code of 404.

When retrieving a Cause using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed. Therefore, please note that the CauseName returned via the API method represents the CauseName as stored within the Issuetrak database. Thus, when retrieving a Cause created through the Issuetrak web interface where HTML encoding of the CauseName is performed, the API consumer may desire to perform additional client-side decoding.

A successful response will include an HTTP status code of 200 (OK) and a response body containing a serialized ReadCauseDTO instance.

ReadCauseDTO
{
 ExtensionData (Array[CustomKeyValuePairDataElement]),
 Metadata (Array[CustomKeyValuePairDataElement]),
 CauseID (integer),
 CauseName (string),
 DisplayOrder (number)
}
CustomKeyValuePairDataElement
{
Key (string),
Value (object)
}

Request HTTP Verb: GET

Response Status Codes:

• Success: 200
• Invalid Cause ID: 400 (Bad Request, e.g., a negative integer is supplied)
• Non-existent Cause: 404
• Invalid Cause ID: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)

Response Properties:

• The ExtensionData property is not used in version 1 of the API.
• The Metadata property provides a key / value collection of additional data about the API operation and / or the response body.

Sample Request URL: ~/api/v1/causes/11

{
 “ExtensionData”: [],
 “Metadata”: [
  {
   “Key”: “APIVersion”,
   “Value”: “v1”
  },
  {
   “Key”: “QueryDate”,
   “Value”: “2014-12-09T20:19:23.9695584Z”
  }
 ],
 “CauseID”: 11,
 “CauseName”: “Duplicate Ticket”,
 “DisplayOrder”: 0
}

Retrieve all Causes

Description:This API method retrieves a collection of all currently-defined Causes from the Issuetrak data store.

When retrieving a Cause using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed. Therefore, please note that the CauseName returned via the API method represents the CauseName as stored within the Issuetrak database. Thus, when retrieving a Cause created through the Issuetrak web interface where HTML encoding of the CauseName is performed, the API consumer may desire to perform additional client-side decoding.

A successful response will include an HTTP status code of 200 (OK) and a response body containing a serialized collection of ReadCauseDTO instance.

{
 “IsPageIndexZeroBased”: false,
 “PageIndex”: 0,
 “CountForPage”: 0,
 “PageSize”: 0,
 “TotalCount”: 0,
 “Collection”: [
 {
  “ExtensionData”: [
  “KeyValuePair[String,Object]”
  ],
  “Metadata”: [
  “KeyValuePair[String,Object]”
  ],
  “CauseID”: 0,
  “CauseName”: "",
  “DisplayOrder”: 0
  }
 ]
}

Request HTTP Verb: GET

Response Status Codes:

• Success: 200
• Non-existent Cause: 404

Response Properties:

• The IsPageIndexZeroBased property value is always true. This property is included for use in future API versions.
• The PageIndex property value is always 0. This property is included for use in future API versions.
• The CountForPage property value is always the same as TotalCount. This property is included for use in future API versions.
• The PageSize property value is always the maximum value for a signed, 32-bit integer. This property is included for use in future API versions.
• The TotalCount property value is the number of records returned in the collection.
• The Collection property is an array containing the ReadCauseDTO objects returned.

Sample Request URL: ~/api/v1/causes/

{
 “IsPageIndexZeroBased”: true,
 “PageIndex”: 0,
 “CountForPage”: 1,
 “PageSize”: 2147483647,
 “TotalCount”: 1,
 “Collection”: [
  {
   “ExtensionData”: [“KeyValuePair[String,Object]”],
   “Metadata”: [“KeyValuePair[String,Object]”],
   “CauseID”: 0,
   “CauseName”: "",
   “DisplayOrder”: 0
  }
 ]
}