API Operations for Departments

Summary

Operation Name: Retrieve a Department by Department ID
Relative API Request Path: ~/api/v1/departments/{departmentID}
HTTP Verb: GET
Description: Retrieve a single Department by Department ID.

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


 

Retrieve a Department by Department ID

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

When retrieving an Department using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed. Therefore, please note that the DepartmentName returned via the API method represents the DepartmentName as stored within the Issuetrak database. Thus, when retrieving a Department created through the Issuetrak web interface where HTML encoding of the DepartmentName 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 ReadDepartmentDTO instance.

Response DTO Schema:
ReadDepartmentDTO
{
 ExtensionData (Array[CustomKeyValuePairDataElement]),
 Metadata (Array[CustomKeyValuePairDataElement]),
 DepartmentID (integer),
 DepartmentName (string),
 IsActive (boolean),
 IsInternal (boolean)
}
CustomKeyValuePairDataElement
{
 Key (string),
 Value (object)
} 

Request HTTP Verb: GET

Response Status Codes:

  • Success: 200
  • Invalid Department ID: 400 (Bad Request, e.g., a negative integer is supplied)
  • Non-existent Department: 404
  • Invalid Department ID: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)
Response Properties:
  • The Metadata property provides a key/value collection of additional data about the API operation and/or the response body.
  • BREAKING CHANGES from Previous API Versions:
    • The “AutoAssignTo” (string) property has been removed as of Issuetrak API 10.0.

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

Sample Response:
{
 “ExtensionData”: [],
 “Metadata”: [
  {
   “Key”: “APIVersion”,
   “Value”: “12.5”
  },
  {
   “Key”: “QueryDate”,
   “Value”: “2014-12-09T20:19:23.9695584Z”
  }
 ],
 “DepartmentID”: 11,
 “DepartmentName”: “Accounting”,
 “IsActive”: true,
 “IsInternal”: true
}

 

Retrieve all Departments

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

When retrieving an Department using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed. Therefore, please note that the DepartmentName returned via the API method represents the DepartmentName as stored within the Issuetrak database. Thus, when retrieving a Department created through the Issuetrak web interface where HTML encoding of the DepartmentName 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 ReadDepartmentDTO instance.

Response DTO Schema:
QueryResultsContainer[ReadDepartmentDTO]
{
 IsPageIndexZeroBased (boolean),
 PageIndex (integer),
 CountForPage (integer),
 PageSize (integer),
 TotalCount (integer),
 Collection (Array[ReadDepartmentDTO])
}
ReadDepartmentDTO
{
 ExtensionData (Array[CustomKeyValuePairDataElement]),
 Metadata (Array[CustomKeyValuePairDataElement]),
 DepartmentID (integer),
 DepartmentName (string),
 IsActive (boolean),
 IsInternal (boolean)
}
CustomKeyValuePairDataElement
{
 Key (string),
 Value (object)
} 

Request HTTP Verb: GET

Response Status Codes:

  • Success: 200
  • Non-existent Department: 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 ReadDepartmentDTO objects returned.
  • BREAKING CHANGES from Previous API Versions:
    • The “AutoAssignTo” (string) property has been removed as of Issuetrak API 10.0.

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

Sample Response:
{
 “IsPageIndexZeroBased”: true,
 “PageIndex”: 0,
 “CountForPage”: 1,
 “PageSize”: 2147483647,
 “TotalCount”: 1,
 “Collection”: [
  {
   "ExtensionData": [],
   "Metadata": [
     {
      "Key": "APIVersion",
      "Value": "12.5"
     },
     {
      "Key": "QueryDate",
      "Value": "2020-12-16T15:28:40.4767848Z"
     }
   ],
   “DepartmentID”: 2,
   “DepartmentName”: "Management",
   “IsActive”: true,
   “IsInternal”: true
  }
 ]
}