Summary
Operation Name: Retrieve a Location by Location ID
Relative API Request Path: ~/api/v1/locations/{locationID}
HTTP Verb: GET
Description: Retrieve a single Location by Location ID.
Operation Name: Retrieve all Locations
Relative API Request Path: ~/api/v1/locations
HTTP Verb: GET
Description: Retrieve a collection of currently defined Locations.
Operation Name: Create a Location (Issuetrak 10.3+)
Relative API Request Path: ~/api/v1/locations
HTTP Verb: Post
Description: Create a new location with a specific LocationID.
Operation Name: Update a Location (Issuetrak 10.3+)
Relative API Request Path: ~/api/v1/locations
HTTP Verb: Put
Description: Update an existing location by specified LocationID.
Retrieve a Location by Location ID
Description: This API method retrieves a Location from the Issuetrak data store for a specified Location ID. The “locationID” parameter must correspond to an existing Location. If there is no such Location ID, an error message will be returned with an HTTP response status code of 404.
When retrieving an Location using the API, no special character decoding (e.g., HTML decoding < as < or > as >) is performed. Therefore, please note that the LocationName returned via the API method represents the LocationName as stored within the Issuetrak database. Thus, when retrieving a Location created through the Issuetrak web interface where HTML encoding of the LocationName 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 ReadLocationDTO instance.
Response DTO Schema:
ReadLocationDTO
{
ExtensionData (Array[CustomKeyValuePairDataElement]),
Metadata (Array[CustomKeyValuePairDataElement]),
LocationID (string),
LocationName (string),
Address1 (string),
Address2 (string),
City (string),
State (string),
Zip (string),
Country (string),
Phone (string),
Phone2 (string),
Fax (string),
Email (string),
ContactPerson (string),
RegionID (integer),
IsActive (boolean),
UserDefined1 (string),
UserDefined2 (string),
UserDefined3 (string),
OrganizationID (integer)
}
CustomKeyValuePairDataElement
{
Key (string),
Value (object)
}
Request HTTP Verb: GET
Response Status Codes:
- Success: 200
- Invalid Location ID: 400 (Bad Request, e.g., a negative integer is supplied)
- Non-existent Location: 404
- Invalid Location 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/locations/11
Sample Response:
{
“ExtensionData”: [],
“Metadata”: [
{
“Key”: “APIVersion”,
“Value”: “12.5”
},
{
“Key”: “QueryDate”,
“Value”: “2020-12-15T18:39:46.5813112Z”
}
],
“LocationID”: “1test”,
“LocationName”: “test”,
“Address1”: “”,
“Address2”: “”,
“City”: “”,
“State”: “”,
“Zip”: “”,
“Country”: “”,
“Phone”: “”,
“Phone2”: “”,
“Fax”: “”,
“Email”: “”,
“ContactPerson”: “”,
“RegionID”: null,
“IsActive”: true,
“UserDefined1”: “”,
“UserDefined2”: “”,
“UserDefined3”: “”,
“OrganizationID”: 1
}
Retrieve all Locations
Description: This API method retrieves a collection of all currently-defined Locations from the Issuetrak data store.
When retrieving an Location using the API, no special character decoding (e.g., HTML decoding < as < or > as >) is performed. Therefore, please note that the LocationName returned via the API method represents the LocationName as stored within the Issuetrak database. Thus, when retrieving a Location created through the Issuetrak web interface where HTML encoding of the LocationName 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 ReadLocationDTO instance.
Response DTO Schema:
QueryResultsContainer[ReadLocationDTO]
{
IsPageIndexZeroBased (boolean),
PageIndex (integer),
CountForPage (integer),
PageSize (integer),
TotalCount (integer),
Collection (Array[ReadLocationDTO])
}
ReadLocationDTO
{
ExtensionData (Array[CustomKeyValuePairDataElement]),
Metadata (Array[CustomKeyValuePairDataElement]),
LocationID (string),
LocationName (string),
Address1 (string),
Address2 (string),
City (string),
State (string),
Zip (string),
Country (string),
Phone (string),
Phone2 (string),
Fax (string),
Email (string),
ContactPerson (string),
RegionID (integer),
IsActive (boolean),
UserDefined1 (string),
UserDefined2 (string),
UserDefined3 (string),
OrganizationID (integer)
}
CustomKeyValuePairDataElement
{
Key (string),
Value (object)
}
Request HTTP Verb: GET
Response Status Codes:
- Success: 200
- Non-existent Location: 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 ReadLocationDTO 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/locations
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-15T18:39:11.8426562Z”
}
],
“LocationID”: “1test”,
“LocationName”: “test”,
“Address1”: “”,
“Address2”: “”,
“City”: “”,
“State”: “”,
“Zip”: “”,
“Country”: “”,
“Phone”: “”,
“Phone2”: “”,
“Fax”: “”,
“Email”: “”,
“ContactPerson”: “”,
“RegionID”: null,
“IsActive”: true,
“UserDefined1”: “”,
“UserDefined2”: “”,
“UserDefined3”: “”,
“OrganizationID”: 1
}
]
}
Create a Location
Description: This API method creates a new Location associated with a specific LocationID within the Issuetrak data store. The CreateLocationDTO object conveys the properties of the new Location. Because LocationID values must be unique, the specified LocationID value must not currently exist. If the LocationID currently exists, an error message will be returned with a 400 HTTP status code.
The response code on success will be 201 (Created), and the response body will represent the text value representing the ID of the newly-created Location.
When creating a Location using the API, no special character encoding (e.g., HTML decoding < as < or > as >) is performed.
All string properties have a maximum length of 50 unless specified otherwise.
Response DTO Schema:
CreateLocationDTO
{
LocationID (string),
LocationName (string),
Address1 (string),
Address2 (string),
City (string),
State (string),
Zip (string),
Country (string),
Phone (string),
Phone2 (string),
Fax (string),
Email (string),
ContactPerson (string),
RegionID (integer),
IsActive (boolean),
UserDefined1 (string),
UserDefined2 (string),
UserDefined3 (string),
OrganizationID (integer)
}
Request HTTP Verb: POST
Response Status Codes:
- Success: 201
- Invalid Data: 400 (Bad Request, e.g., a negative integer is supplied)
- Invalid Location DTO: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)
Response Properties:
- The LocationID property value is required. Maximum length of 25.
- The Locationname property value is required.
- The Address1 property value is not required.
- The Address2 property value is not required.
- The City property value is not required.
- The State property value is not required.
- The Zip property value is not required.
- The Country property value is not required.
- The Phone property value is not required.
- The Phone2 property value is not required.
- The Fax property value is not required.
- The Email property value is not required. Maximum length of 100.
- The ContactPerson property value is not required.
- If the RegionID property value is specified, the value must reference an existing, active Region within the Issuetrak application.
- The IsActive property value is required.
- The UserDefined1 property value is not required.
- The UserDefined2 property value is not required.
- The UserDefined3 property value is not required.
- If the OrganizationID property value is specified, the value must reference an existing Organization within the Issuetrak application.
Sample Request URL: ~/api/v1/locations
Update a Location
Description: This API method updates an existing Location associated with a specific LocationID within the Issuetrak data store. The UpdateLocationDTO object conveys the properties of the Location. If invalid data are supplied, an error message will be returned with a 400 HTTP status code.
The response code on success will be 200 (OK), and the response body will represent the text value representing the ID of the Location.
When updating a Location using the API, no special character encoding (e.g., HTML decoding < as < or > as >) is performed.
All string properties have a maximum length of 50 unless specified otherwise.
Response DTO Schema:
UpdateLocationDTO
{
LocationID (string),
LocationName (string),
Address1 (string),
Address2 (string),
City (string),
State (string),
Zip (string),
Country (string),
Phone (string),
Phone2 (string),
Fax (string),
Email (string),
ContactPerson (string),
RegionID (integer),
IsActive (boolean),
UserDefined1 (string),
UserDefined2 (string),
UserDefined3 (string),
OrganizationID (integer)
}
Request HTTP Verb: PUT
Response Status Codes:
- Success: 201
- Invalid Data: 400 (Bad Request, e.g., a negative integer is supplied)
- Invalid Location DTO: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)
Response Properties:
- The LocationID property value is required. Maximum length of 25.
- The LocationName property value is required.
- The Address1 property value is not required.
- The Address2 property value is not required.
- The City property value is not required.
- The State property value is not required.
- The Zip property value is not required.
- The Country property value is not required.
- The Phone property value is not required.
- The Phone2 property value is not required.
- The Fax property value is not required.
- The Email property value is not required.
- The ContactPerson property value is not required. Maximum length of 100.
- If the RegionID property value is specified, the value must reference an existing, active Region within the Issuetrak application.
- The IsActive property value is not required.
- The UserDefined1 property value is not required.
- The UserDefined2 property value is not required.
- The UserDefined3 property value is not required.
- If the OrganizationID property value is specified, the value must reference an existing Organization within the Issuetrak application.
Sample Request URL: ~/api/v1/locations
