API Operation Conventions

DATA TRANSFER OBJECTS

The Issuetrak API 11.0 uses the concept of Data Transfer Objects (DTOs) to represent the serialized input to API operation endpoints for API methods that use the POST and PUT HTTP verbs and to represent the serialized output from API operations where a response object is expected.

DATE SERIALIZATION

For serializing dates, the Issuetrak API 11.0 uses the ISO 8601 standard. For example, the date February 27, 2014, at 11:30:10 AM, is represented in the ISO 8601 standard as: 2014-02-27T11:30:10.0000000.

DATA SERIALIZATION

The Issuetrak API 11.0 supports two serialization formats: JSON and XML. The documentation assumes the use of JSON; however, the Issuetrak API 11.0 Swagger UI demonstrates the alternate serialization response schema for XML if an XML implementation is desired.

EXTENSIONDATA AND METADATA OBJECTS

For API operation responses that generate DTOs or collections of DTOs, there are two additional properties that will be present within each of the DTO instances, “ExtensionData” and “Metadata”. The ExtensionData property represents a collection of key/value pairs and is intended to provide a container for conveying data that is external to an established data contract. One of the primary uses of this property would be to convey data from a future version of a DTO contract (e.g., a future version of a response DTO from a version X implementation of the Issuetrak API) to a previous DTO version.

The Metadata property represents a collection of key/value pairs and is intended to provide a container for conveying data that pertinent to the individual API operation. For API operations that produce response DTO instances, the Metadata collection will include at least two properties: “APIVersion” and “QueryDate”. The “APIVersion” property will provide a text representation of the version of the API used to generate the response, e.g., “v1”. The “QueryDate” property will provide an ISO 8601 serialized date representing the date time that the API operation was run.