API Operations for Notes

Summary

Operation Name: Retrieve a Note by Note ID
Relative API Request Path: ~/api/v1/notes/{noteID}
HTTP Verb: GET
Description: Retrieve a single Note from the database by Note ID.

Operation Name: Retrieve a Collection of Notes by Issue Number
Relative API Request Path: ~/api/v1/notes/issue/{issueNumber}
HTTP Verb: GET
Description: Retrieve a collection of Notes from the database by their associated issueNumber.

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

Retrieve a Note by Note ID

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

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

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

Response DTO Schema:

ReadNoteDTO
{
 ExtensionData (array[KeyValuePair[String,Object]]),
 Metadata (array[KeyValuePair[String,Object]]),
 NoteID (integer),
 IssueNumber (integer),
 CreatedDate (ISO 8601 string),
 CreatedBy (string),
 ModifiedBy (string),
 ModifiedDate (ISO 8601 string),
 NoteText (string),
 IsPrivate (boolean),
 IsRichText (boolean)
}

Request HTTP Verb: GET

Response Status Codes:

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

Response DTO Property Notes:

  • 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/notes/102

Sample Response:

{
 “ExtensionData”: [],
 “Metadata”: [
  {
   “Key”: “APIVersion”,
   “Value”: “v1”
  },
  {
   “Key”: “QueryDate”,
   “Value”: “2014-10-08T16:06:58.6146552Z”
  }
 ],
 “NoteID”: 102,
 “IssueNumber”: 1,
 “CreatedDate”: “2011-06-22T18:55:30.47”,
 “CreatedBy”: “Admin”,
 “ModifiedBy”: “Admin”,
 “ModifiedDate”: “2014-08-22T12:11:30.063”,
 “NoteText”: “What I've done”,
 “IsPrivate”: true,
 “IsRichText”: true
}

Retrieve a Collection of Notes by Issue Number

Description: 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.

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

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

Response DTO Schema:

{
 “IsPageIndexZeroBased”: false,
 “PageIndex”: 0,
 “CountForPage”: 0,
 “PageSize”: 0,
 “TotalCount”: 0,
 “Collection”: [
  {
   “ExtensionData”: [
    “KeyValuePair[String,Object]”
   ],
   “Metadata”: [
    “KeyValuePair[String,Object]”
   ],
   “NoteID”: 0,
   “IssueNumber”: 0,
   “CreatedDate”: “ISO 8601 string”,
   “CreatedBy”: "",
   “ModifiedBy”: "",
   “ModifiedDate”: “ISO 8601 string”,
   “NoteText”: "",
   “IsPrivate”: false,
   “IsRichText”: false
  }
 ]
}

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: 400
  • 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 ReadNoteDTO objects returned.
  • The ExtensionData property is not implemented in v1 of the API.

Sample Request URL: ~/api/v1/notes/issue/6

Sample Response:

{
 “IsPageIndexZeroBased”: true,
 “PageIndex”: 0,
 “CountForPage”: 1,
 “PageSize”: 2147483647,
 “TotalCount”: 1,
 “Collection”: [
  {
   “ExtensionData”: [],
   “Metadata”: [
    {
     “Key”: “APIVersion”,
     “Value”: “v1”
    },
    {
     “Key”: “QueryDate”,
     “Value”: “2014-10-08T16:24:53.1827312Z”
    }
   ],
   “NoteID”: 140,
   “IssueNumber”: 6,
   “CreatedDate”: “2011-06-23T10:55:37.81”,
   “CreatedBy”: “TestUser”,
   “ModifiedBy”: null,
   “ModifiedDate”: null,
   “NoteText”: “No action needed”,
   “IsPrivate”: true,
   “IsRichText”: true
  }
 ]
}

Create a Note for an Issue

Description: This API method creates a new Note associated with a specific Issue (identified by IssueNumber) within the Issuetrak data store. The CreateNoteDTO object conveys the properties of the new Note. Because Notes 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.

The response code on success will be 201 (Created), and the response body will represent the 32-bit integer value representing the ID of the newly-created Note.

When creating a Note using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed. This deviates from the process when creating a Note through the Issuetrak web interface where HTML encoding of the NoteText is performed.

Response DTO Schema:

CreateNoteDTO
{
 IssueNumber (integer),
 CreatedDate (ISO 8601 string),
 CreatedBy (string),
 ShouldSuppressEmailForCreateOperation (boolean),
 NoteText (string),
 IsPrivate (boolean),
 IsRichText (boolean)
}

Request HTTP Verb: POST

Response Status Codes:

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

Response DTO Property Notes:

  • The ShouldSuppressEmailForCreateOperation property value determines whether or not email notifications will be sent by Issuetrak during the creation of this Note. If ‘false', email notifications will be sent normally. If 'true’, email notifications will not be sent.
  • The CreatedBy property value must reference an existing, active User within the Issuetrak application.

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

Sample Request:

{
 “IssueNumber”: 6,
 “CreatedDate”: “2014-01-01T11:30:10.0000000”,
 “CreatedBy”: “Admin”,
 “ShouldSuppressEmailForCreateOperation”: false,
 “NoteText”: “This is a test public note.”,
 “IsPrivate”: false,
 “IsRichText”: false
}

Sample Response HTTP Status Code: 201

Sample Response Body: 123101 (represents the newly-created Note ID)