API Operations for Attachments

Summary

Operation Name: Retrieve an Attachment by Attachment ID
Relative API Request Path: ~/api/v1/attachments/{attachmentID}/{includeAttachmentContent}
HTTP Verb: GET
Description: Retrieve a single Attachment from by its AttachmentID with the option of specifying whether or not to retrieve the attachment file content.

Operation Name: Retrieve a Collection of Attachments by Issue Number
Relative API Request Path: ~/api/v1/attachments/issue/{issueNumber}/{includeAttachmentContent}
HTTP Verb: GET
Description: Retrieve a collection of Attachments for an associated issueNumber with the option of specifying whether or not to retrieve the attachment file content.

Operation Name: Retrieve a Collection of Attachments by IssueNumber with the Contents of the Attachments Compressed as a ZIP Archive
Relative API Request Path: ~/api/v1/attachments/compressed/issueNumber/{issueNumber}
HTTP Verb: GET
Description: Retrieve a collection of Attachments for an associated issueNumber with the contents of the attachment compresses as a ZIP Archive.

Operation Name: Create Attachment for Issue
Relative API Request Path: ~/api/v1/attachments
HTTP Verb: POST
Description: Create a new Attachment for an Issue.


Retrieve an Attachment by Attachment ID

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

The “includeAttachmentContent” parameter is an optional parameter that defaults to true. If false, (e.g., /attachments/1/false), the ReadAttachmentDTO FileContent property will be null representing the skipped operation of retrieving the attachment file content.

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

Response DTO Schema:

  • ReadAttachmentDTO
{
     ExtensionData (array[CustomKeyValuePairDataElement [String,Object]]),
     Metadata (array[CustomKeyValuePairDataElement [String,Object]]),
     AttachmentID (integer),
     IssueNumber (integer),
     FileName (string),
     CreatedBy (string),
     CreatedDate (ISO 8601 string),
     FileSizeInBytes (integer),
     FileContent (base-64 string)
}

Request HTTP Verb: GET

Response Status Codes:

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

Response DTO Property Notes:

  • The FileSizeInBytes property value should equal the number of bytes present in the FileContent byte array after decoding from base-64.
  • The FileContent property will contain the base-64 encoded contents of the Attachment file.
  • The ExtensionData property will contain an echo of the “includeAttachmentContent” parameter setting for the request.
  • 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/attachments/139978/true

Sample Response:

{
  “ExtensionData”: [
   {
    “Key”: “includeAttachmentContent”,
    “Value”: true
   }
  ],
  “Metadata”: [
   {
    “Key”: “APIVersion”,
    “Value”: “v1”
   },
   {
    “Key”: “QueryDate”,
    “Value”: “2014-10-08T14:52:42.564023Z”
   }
  ],
  “AttachmentID”: 139978,
  “IssueNumber”: 1,
  “FileName”: “Test-File-200afea2-73f3-4fbf-8b66-33a2f8e2464e.txt”,
  “CreatedBy”: “Admin”,
  “CreatedDate”: “2014-10-03T13:50:04.607”,
  “FileSizeInBytes”: 100,
  “FileContent”: “VGhpcyBub3RlIHRleHQgd2FzIGNyZWF0ZWQgb24gMTAvMy8yMDE0IDE6NTA6MDQgUE0uICBSYW5kb20gdGV4dCBmb2xsb3dzOg0KQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQQ==”
}

Retrieve a Collection of Attachments by Issue Number

Description: This API method retrieves a collection of Attachment from the Issuetrak data store for the specified Issue Number. The “issueNumber” parameter must correspond to an existing Issue. If there is no such IssueNumber, an error message will be returned with an HTTP response status code of 400.

The “includeAttachmentContent” parameter is an optional parameter that defaults to true. If false, (e.g., /attachments/1/false), the ReadAttachmentDTO FileContent property will be null representing the skipped operation of retrieving the attachment file content.

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

Response DTO Schema:

{
  “IsPageIndexZeroBased”: false,
  “PageIndex”: 0,
  “CountForPage”: 0,
  “PageSize”: 0,
  “TotalCount”: 0,
  “Collection”: [
  {
     ExtensionData[],
     Metadata[],
     “AttachmentID”: 0,
     “IssueNumber”: 0,
     “FileName”: "",
     “CreatedBy”: "",
     “CreatedDate”: “ISO 8601 string”,
     “FileSizeInBytes”: 0,
     “FileContent”: “Base64 string”
  }
 ]
}

Request HTTP Verb: GET

Response Status Codes:

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

Response DTO Property Notes:

  • 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 ReadAttachmentDTO objects returned.
  • The ExtensionData property will contain an echo of the “includeAttachmentContent” parameter setting for the request.

Sample Request URL: ~/api/v1/attachments/issueNumber/122/true

Sample Response:

{
 “IsPageIndexZeroBased”: true,
 “PageIndex”: 0,
 “CountForPage”: 1,
 “PageSize”: 2147483647,
 “TotalCount”: 1,
 “Collection”: [
 {
   “ExtensionData”: [
    {
     “Key”: “includeAttachmentContent”,
     “Value”: true
    }
   ],
   “Metadata”: [
    {
     “Key”: “APIVersion”,
     “Value”: “v1”
    },
    {
     “Key”: “QueryDate”,
     “Value”: “2014-10-08T15:07:03.499441Z”
    }
   ],
   “AttachmentID”: 138907,
   “IssueNumber”: 122,
   “FileName”: “AttachmentTestFile.txt”,
   “CreatedBy”: “admin”,
   “CreatedDate”: “2014-08-06T02:01:19”,
   “FileSizeInBytes”: 47,
   “FileContent”: “VGhpcyBpcyBhIHRlc3QgdGV4dCBmaWxlDQpIZXJlJ3MgbW9yZSB0ZXN0IHRleHQ=”
  }
 ]
}

Retrieve a Collection of Attachments by IssueNumber with the Contents of the Attachments Compressed as a ZIP Archive

Description:This API method retrieves a collection of Attachment from the Issuetrak data store for the specified Issue Number. The “issueNumber” parameter must correspond to an existing Issue. If there is no such IssueNumber, an error message will be returned with an HTTP response status code of 400.

The content of the retrieved attachments are compressed as a ZIP archive.

A successful response will include an HTTP status code of 200 (OK) and a response body containing a serialized “QueryResults” instance with a Collection property containing a set of ReadAttachmentDTO instances. For each of the ReadAttachmentDTO instances, the FileContent property will be null and the ExtensionData property will contain a key/value pair with the key name, “CompressedEntryName”. The value of the “CompressedEntryName” key will represent the name of the ZIP archive entry corresponding to the byte content for the ReadAttachmentDTO instance’s compressed content.

A successful response will include a second root object, “CompressedAttachmentsContent”, representing the Base-64 encoded representation of the ZIP archive of the attachments for the queried Issue.

Response DTO Schema:

{
 “ExtensionData”: [
  {
   “Key”: “string”,
   “Value”: {}
  }
 ],
 “Metadata”: [
  “CustomKeyValuePairDataElement”
 ],
 “QueryResults”: {
  “IsPageIndexZeroBased”: true,
  “PageIndex”: 0,
  “CountForPage”: 0,
  “PageSize”: 0,
  “TotalCount”: 0,
  “Collection”: [
   {
    “ExtensionData”: [
     “CustomKeyValuePairDataElement”
    ],
    “Metadata”: [
     “CustomKeyValuePairDataElement”
    ],
    “AttachmentID”: 0,
    “IssueNumber”: 0,
    “FileName”: “string”,
    “CreatedBy”: “string”,
    “CreatedDate”: “string”,
    “FileSizeInBytes”: “string”,
    “FileContent”: {}
   }
  ]
 },
 “CompressedAttachmentsContent”: {}
}

Request HTTP Verb: GET

Response Status Codes:

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

Response DTO Property Notes:

  • 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 ReadAttachmentDTO objects returned.
  • The ExtensionData properties for the ReadAttachmentDTO instances included within the QueryResults Collection will contain a key/value pair with the key name, “CompressedEntryName”, representing the ZIP archive entry name for the attachment. The “CompressedEntryName” is randomly-generated value for every request to allow attachments with the same base name to be compressed.

Sample Request URL: ~/api/v1/attachments/compressed/issueNumber/105557

Sample Response:

{
 “ExtensionData”: [],
 “Metadata”: [
  {
   “Key”: “APIVersion”,
   “Value”: “v1”
  },
  {
   “Key”: “QueryDate”,
   “Value”: “2015-02-27T15:04:57.4014992Z”
  }
 ],
 “QueryResults”: {
  “IsPageIndexZeroBased”: true,
  “PageIndex”: 0,
  “CountForPage”: 1,
  “PageSize”: 2147483647,
  “TotalCount”: 1,
  “Collection”: [
  {
   “ExtensionData”: [
    {
     “Key”: “CompressedEntryName”,
     “Value”: “4p0mlcq1.yjm”
    }
   ],
   “Metadata”: [],
   “AttachmentID”: 141019,
   “IssueNumber”: 105557,
   “FileName”: “Test-Attachment-File.txt”,
   “CreatedBy”: “Admin”,
   “CreatedDate”: “2015-02-24T12:25:17.993”,
   “FileSizeInBytes”: 5000000,
   “FileContent”: null
  },
  {
   “ExtensionData”: [
    {
     “Key”: “CompressedEntryName”,
     “Value”: “wsdf4zni.uzj”
    }
   ]
  ]
 },
  “CompressedAttachmentsContent”: “UEsDBBQAAAAIAJxQW0YcTJk/CxMAAEBLTAAMAAAANHAwbWxjcTEueWpt7MGBAAAAAIAgtv2lFqkKAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA ==”
}

Create Attachment for Issue

Description: This method creates a new Attachment associated with a specific Issue (identified by IssueNumber) within the Issuetrak data store. The CreateAttachmentDTO object conveys the properties and file content of the new Attachment. Because Attachments are associated with Issues, the IssueNumber property of the DTO must correspond to an existing Issue. If there is no such IssueNumber, an error message will be returned with a 400 HTTP status code.

A successful response will include an HTTP status code of 201 (Created), and the response body will represent the 32-bit integer value representing the ID of the newly-created Attachment.*

Response DTO Schema:

CreateAttachmentDTO

{
     IssueNumber (integer),
     FileName (string),
     CreatedBy (string),
     CreatedDate (ISO 8601 string),
     FileSizeInBytes (integer),
     FileContent (Base64 string)
}

Request HTTP Verb: POST

Response Status Codes:

  • Success: 201 (Created)
  • Invalid Data: 400
  • Non-existent Issue: 400

Response DTO Property Notes:

  • The FileName property value must comply with the character limitations imposed on standard Windows file names.
  • The CreatedBy property value must reference an existing, active User within the Issuetrak application.
  • The FileSizeInBytes property value must match the number of bytes present in FileContent after decoding from base-64.
  • The FileContent property value must contain the base-64-encoded contents of the Attachment file.

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

Sample Request:

{
 “IssueNumber”: 100,
 “FileName”: “Test-Attachment.txt”,
 “CreatedBy”: “Admin”,
 “CreatedDate”: “2014-01-01T11:30:10.0000000”,
 “FileSizeInBytes”: 26,
 “FileContent”: “VGhpcyBpcyBhIHRlc3QgYXR0YWNobWVudC4=”
}

Sample Response HTTP Status Code: 201

Sample Response Body: 140367 (represents the newly-created Attachment ID)