Issuetrak API

Issuetrak API
An overview of methodology and processes
within the Issuetrak API
This document provides insight into the technical design goals and technical implementation within the
upcoming Issuetrak API to provide stakeholders with background to evaluate the utility of the Issuetrak
API especially when employed for enterprise-level data operations targeting the Issuetrak product
platform.

table of contents
Abstract............................................................................................................................................................... 4
Overview............................................................................................................................................................. 4
Motivation for a New Issuetrak API................................................................................................................. 4
I: API Design Goals............................................................................................................................................ 5
Versioning....................................................................................................................................................... 5
Scope of Versioning .................................................................................................................................. 6
Implementation of Versioning................................................................................................................. 7
Asynchrony................................................................................................................................................... 10
Asynchronous File I/O............................................................................................................................. 10
Asynchronous Database Operations.................................................................................................... 11
Task-based Asynchronous Patterns ..................................................................................................... 12
Transactional Processing............................................................................................................................ 13
ACID in Transactions............................................................................................................................... 13
Transaction Management in the Issuetrak API ................................................................................... 13
Exception Handling ..................................................................................................................................... 14
Categorization of Exceptions................................................................................................................. 14
Deadlocks as an Example of a Recoverable Exceptions .................................................................... 15
Globalization ................................................................................................................................................ 15
Language Resources............................................................................................................................... 15
Date Resources........................................................................................................................................ 16
Response Encoding................................................................................................................................. 17
II: API Developer-Oriented Resources.......................................................................................................... 18
Overview....................................................................................................................................................... 18
Swagger™ UI Integration ............................................................................................................................ 18
Overview of the Swagger™ Specification ............................................................................................. 18
Swagger Implementation within the Issuetrak API............................................................................. 18
Logging.......................................................................................................................................................... 20
General Logging ...................................................................................................................................... 20
On-Demand Request Logging ............................................................................................................... 21
Data Serialization......................................................................................................................................... 22

Overview................................................................................................................................................... 22
Implementation of Serialization within the Issuetrak API ................................................................. 22
Exception Management.............................................................................................................................. 24
Overview................................................................................................................................................... 24
ELMAH Integration.................................................................................................................................. 24
III: Conclusions................................................................................................................................................ 25
Business Benefits ........................................................................................................................................ 25
Resources..................................................................................................................................................... 25
Works Cited ...................................................................................................................................................... 26
Appendix 1: On Demand Request Logging Output Text Sample (Excerpt) ............................................ 29

abstract
This document provides insight into the technical design goals and technical implementation within the
Issuetrak API to provide stakeholders with background to evaluate the utility of the Issuetrak API
especially when employed for enterprise-level data operations targeting the Issuetrak product platform.
overview
This document is divided into two main sections: API Design Goals and API Developer-Oriented Resources.
The API Design Goals section discusses five key technology areas that are implemented within the
Issuetrak API including Versioning, Asynchrony, Exception Handling, Transaction Support, and
Globalization. The API Developer-Oriented Resources section discusses the API resources that are
provided to support efficient and practical software development using the Issuetrak API.
motivation for a new Issuetrak API
Why was another Issuetrak API created? An existing SOAP
1
-based API has been available for the Issuetrak
product for several iterations; however, the SOAP API represents an older technology stack without
support for more modern web API conventions
such as the choice of different response
serialization formats including JSON
2
or XML
3
,
versioning support, and advanced resources
support via technologies such as asynchronous
processing.
In modern web APIs, SOAP-based service APIs have
been supplanted by REST4
ful APIs because the
complexity of the conventions and services
implemented by SOAP including WS-Security
5
, WS-
AtomicTransaction
6
, and WS-ReliableMessaging
7
are
often either not needed or can be implemented in a
simpler manner by leveraging either the anchor
points of the hosting infrastructure or by wrapping
the existing application’s implementation of such functionality.
1
SOAP: Simple Object Access Protocol (See http://www.w3.org/TR/soap/ for a list of current SOAP specifications)
2
JSON: JavaScript Object Notation, “…a lightweight data-interchange format” (See http://json.org/)
3
XML: Extensible Markup Language, “…a simple, very flexible text format derived from SGML” (See http://www.w3.org/XML/)
4
REST: Representational State Transfer
5
WS-Security: Web Services Security (See https://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-
SOAPMessageSecurity.pdf)
6
WS-AtomicTransaction: Web Services Atomic Transaction (See http://docs.oasis-open.org/ws-tx/wstx-wsat-1.1-spec-errata-os/wstx-
wsat-1.1-spec-errata-os.html)
7
WS-ReliableMessaging: Web Services Reliable Messaging (See http://docs.oasis-open.org/ws-rx/wsrm/200702)
SOAP Version 1.2 provides the
definition of the XML-based
information which can be used for
exchanging structured and typed
information between peers in a
decentralized, distributed
environment.
(World Wide Web Consortium,
2007)

In particular, for an existing web application such as Issuetrak,
moving to a REST-based web API provides a logical shift because
the same HTTP8
protocol used by the web application is also
used for the API access. In addition, to sharing the same
communication protocol, RESTful service APIs can provide
better development platforms with support for different data
serialization formats such as JSON and XML, better support for
data caching, and easier integration with web browser client
software.
One of the lead architects for RESTful API architectures, Roy
Fielding, defines the principles of the REST architecture in his 2000 doctoral dissertation:
The Representational State Transfer (REST) style is an abstraction of the
architectural elements within a distributed hypermedia system. REST ignores the
details of component implementation and protocol syntax in order to focus on the
roles of components, the constraints upon their interaction with other
components, and their interpretation of significant data elements. It encompasses
the fundamental constraints upon components, connectors, and data that define
the basis of the Web architecture, and thus the essence of its behavior as a
network-based application. (Fielding R. T., 2000)
Drawing upon the key themes within this definition from Fielding, the Issuetrak API seeks to define in clear
terms the “roles of components” for the processing of the “significant data elements” within the Issuetrak
application’s data domain including Issues, Notes, and Attachments by providing an API architecture that
is abstracted from the Issuetrak web application interface and that is tuned for the efficient processing of
data especially for data originating from electronic peers.
i: API design goals
versioning
People tend to think of the web as a way to get information or perhaps as a place to
carry out ecommerce. But really, the web is about accessing applications. Think of each
website as an application, and every single click, every single interaction with that site, is
an opportunity to be on the very latest version of that application.
--Marc Andreessen (Anderson, 2012)
Versioning is crucially important because it represents the fulfillment of a contract, the implementation of
a software Hippocratic oath as it were. Just as ancient doctors swore, “I will use those dietary regimens
which will benefit my patients according to my greatest ability and judgment, and I will do no harm or
injustice to them.” (U.S. National Library of Medicine, 2002), so too do the implementers of a versioned API
affirm that the software contract established in the past and associated with the version of the API being
accessed in the present will accept input consistent with the established request interfaces and will deliver
output consistent within the established response mechanisms.
8
HTTP: Hypertext Transfer Protocol (See http://www.w3.org/Protocols/rfc2616/rfc2616.html)
Key REST Architectural
Constraints
1) Client-Server
2) Stateless
3) Cacheable
(Fielding R. T., 2000)

scope of versioning
The Issuetrak API applies versioning to the defined operations of the API including the documentation
portal.
For example, for accessing the Note defined for a Note entity with a NoteID = 102, the following URL9
is
used:
https://local.Issuetrakapi.com/v1/notes/102
This URL has several key parts as displayed in Table 1.
Table 1: URL Components for a Sample Versioned API URL
URL
Component
URL Component Value Comments
Protocol https Secure Hypertext Transfer Protocol
Hostname local.Issuetrakapi.com Since a port is not explicitly defined, the
default https port of 443 is assumed.
Path /v1/notes/102 Within the path, the resource route is defined
in progressive steps.
First, the API version is encoded as “v1”.
Second, the API controller is specified as
“notes”.
Third, the resource identifier, e.g., the Note
entity with NoteID = 102 is specified.
The Issuetrak API applies versioning not only to all API operation endpoints against the Notes, Issues, and
Attachments entities but also to the API documentation portal implemented via the API’s Swagger portal.
9
URL: Uniform Resource Locator, a form of URI: Uniform Resource Identifier (See RFC 3986 http://www.ietf.org/rfc/rfc3986.txt)

implementation of versioning10
There were three main contenders for the implementation of versioning within the Issuetrak API:
1. URL Versioning
In URL versioning, an identifier (often a positive integer preceded by the letter “v” for version) is
embedded within the request URL for each access of the API.
2. Custom Request Header Versioning
In Custom Request Header versioning, the desired target API version is encoded via a custom
HTTP header
11
key/value pair, e.g., “Issuetrak-API-Version:1”.
3. Accept Header Versioning
In Accept Header versioning, the desired target API version is encoded within the HTTP Accept
header, e.g., “Accept: text/html,application/xhtml+xml,application/xml;v=1”
One advantage of applying the versioning within the URL is that there is a clear semantic signal as to the
anticipated contract for the request and response for the API operation. In addition, there are no
additional burdens placed upon the developer to properly encode the versioning within either a custom
request HTTP header or within the “Accept” HTTP standard header.
The Accept Header Versioning option was rejected because it would have introduced per-request
processing overhead that was deemed unnecessary. The HTTP Accept request-header field does permit
the inclusion of various “accept-extension” elements of the following form:
accept-extension = ";" token [ "=" ( token | quoted-string ) ]
(Internet Engineering Task Force (IETF) , 2014)
However, given that the “Accept” header already includes an option for specifying a relative quality factor
for each specified “media-range” element (Internet Engineering Task Force (IETF) , 2014), the additional
text parsing that would be needed to accurately extract version request information while preserving the
traditional parsing of the “Accept” header’s value information was deemed unnecessary overhead.
A traditional argument against the use of URL versioning for a RESTful API is that since the URLs issued
within RESTful API requests represent resources, to encode versioning information within the resource
identifier is tantamount to coupling implementation with interface.
Indeed, as Roy Fielding notes in his blog article entitled “REST APIs must be hypertext-driven”:
A REST API must not define fixed resource names or hierarchies (an obvious
coupling of client and server). Servers must have the freedom to control their own
namespace. Instead, allow servers to instruct clients on how to construct
appropriate URIs, such as is done in HTML forms and URI templates, by defining
those instructions within media types and link relations. [Failure here implies that
clients are assuming a resource structure due to out-of band information, such as
10
For an informative and entertaining overview of the various API versioning techniques that are available as well as an explanation
of the pros and cons of the various techniques, see the posting by Troy Hunt: “Your API versioning is wrong, which is why I decided
to do it 3 different wrong ways” at: http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html.
11
HTTP headers are part of the HTTP 1.1 specification (See RFC2616 at http://www.w3.org/Protocols/rfc2616/rfc2616.html). For a list
of standard HTTP headers, refer to Section 14 “Header Field Definitions” of the HTTP 1.1 specification (See
http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)

a domain-specific standard, which is the data-oriented equivalent to RPC's
functional coupling]. (Fielding R. T., 2008)
Notwithstanding these insightful REST architectural principles, the use of the URL versioning scheme
promotes and promises a stable implementation contract that is the easiest to develop against and that
produces lower overhead in the server-side interpretation of each API request.
An emerging constraint of the REST architecture that provides an implementation in accordance with
Fielding’s comments is HATEOAS
12
(Hypertext As The Engine Of Application State). The HATEOAS
constraint provides options for additional operations to be performed for a resource via resource
representations. In typical implementations, these resource representations are delivered via link
elements with the “rel” attribute denoting the relationship of the resource representation to the original
resources and the “href” attribute for the link element providing a URL to the resource.
Martin Fowler considers HATEOAS as the “Level 3” implementation of the Richardson Maturity Model, an
API maturity heuristic developed by Leonard Richardson. (Fowler, 2010) In Fowler’s view, the HATEOAS
constraint provides the Hypermedia Controls for the Richardson Maturity Model.
The point of hypermedia controls is that they tell us what we can do next, and the
URI of the resource we need to manipulate to do it. Rather than us having to know
where to post our appointment request, the hypermedia controls in the response
tell us how to do it. (Fowler, 2010)
As an example, consider a JSON-serialized response issued to the GET request to the URL in Error!
Reference source not found..
Listing 1: Sample Versioned URL to Retrieve a Note by ID
https://local.Issuetrakapi.com/v1/notes/102
12
HATEOAS: Hypermedia as the Engine of Application State (See http://en.wikipedia.org/wiki/HATEOAS for an overview)

If the Note object is modeled as having only NoteID (integer) and NoteText (string) properties similar to
the pseudo-C# class displayed in Error! Reference source not found..
Listing 2: C# Pseudo-class Modeling a Note
class Note
{
Int32 NoteID;
String NoteText;
}
A typical JSON-serialized response is illustrated in Error! Reference source not found..
Listing 3: Pseudo-JSON Serialization for Pseudo-Class from Listing 2
{
“NoteID” : 102,
“NoteText” : “This is the text for the note.”
}
A HATEOAS-enabled response would is illustrated in Error! Reference source not found..
Listing 4: Pseudo-HATEOAS Response for Pseudo-Class from Listing 1
{
“NoteID” : 102,
“NoteText” : “This is the text for the note.”,
“Links” :
[
{
“rel” : “self”,
“href” : “https://local.Issuetrakapi.com/v1/notes/102”
}
]
}
The Issuetrak API does not currently implement HATEOAS; although, future iterations may introduce this
constraint. Within the HATEOAS implementation, there is an increase in the response size even though
most consumers of the Issuetrak API will develop within the context of systems for which the API
endpoints are well-defined without the need for hypermedia control queries. Additionally, HATEOAS
relies upon the injection of additional semantic understanding beyond the ability of most API software
clients. Finally, there are some emerging open-source projects
13
that support HATEOAS especially within
the context of Web API projects, but clear standards have not yet emerged.
13
For one such example, see the article “Generating Hypermedia links in ASP.NET Web API” by Ben Foster at
http://benfoster.io/blog/generating-hypermedia-links-in-aspnet-web-api

asynchrony
There is nothing of which we are apt to be lavish as of Time and about which we ought
be more solicitous; since without it we can nothing in this World. Time is what we want
most, but what, alas! we use worst ; and for which God will certainly most strictly reckon
us, when Time shall be no more.
--William Penn (Penn, 1682)
Microsoft.NET developers were granted an extraordinary gift commencing with the release of the Task
Parallel Library (TPL) in .NET 4.0. As summarized in the MSDN article providing an overview of the TPL:
The purpose of the TPL is to make developers more productive by simplifying the
process of adding parallelism and concurrency to applications. The TPL scales the
degree of concurrency dynamically to most efficiently use all the processors that
are available. In addition, the TPL handles the partitioning of the work, the
scheduling of threads on the ThreadPool, cancellation support, state management,
and other low-level details. (Microsoft Corporation, 2014)
Threading techniques that once required a advanced technical knowledge of operating system internals,
careful synchronization practices, and fastidious testing have been simplified by the TPL. In addition, for
areas of an application that may benefit from parallelization or concurrent execution, the TPL often
provides the best balance of performance, safety, and reliability to split computational loads across cores
or physical processors.
Commencing in Microsoft.NET 4.5, an even more extraordinary gift was provided with asynchronous
function extensibility and the “async” modifier and “await” operator. The asynchronous function
extensibility builds upon the support provided by the TPL and simplifies the development of applications
that use asynchronous functionality, especially asynchronous I/O
14
operations.
By marking a method with the “async” modifier15
, the compiler will build an optimized state machine in
the background to handle the synchronization of state data to and from the delegate to be executed.
Used within methods, lambda expressions16
, or anonymous methods17
, the “await” operator18
suspends
the execution of a task until the task completes execution.
Within the Issuetrak API, asynchronous practices are employed in several ways using asynchronous file
I/O, asynchronous database operations, and task-based asynchronous patterns.
asynchronous file I/ O
The Issuetrak API interacts with attachments exclusively using asynchronous file I/O. Since the CLR I/O
methods wrap internal Win32 API functionality, careful attention must be paid to use the appropriate
14
I/O: Input/Output
15
See “async (C# Reference)” at http://msdn.microsoft.com/en-us/library/hh156513.aspx
16
See “Lamda Expressions” at http://msdn.microsoft.com/en-us/library/bb397687.aspx
17
See “Anonymous Methods” at http://msdn.microsoft.com/en-us/library/0yw3tz5k.aspx
18
See “await (C# Reference)” at http://msdn.microsoft.com/en-us/library/hh156528.aspx

stream instance constructor so that the stream instance is capable of using overlapped I/O19
for true
asynchronous operations wherein the file handle is opened for overlapped I/O. As the MSDN article on
the FileStream IsAsync property notes:
When the IsAsync property is false and you call the asynchronous read and write
operations, the UI thread is still not blocked, but the actual I/O operation is
performed synchronously. (Microsoft Corporation, 2014)
Therefore, Issuetrak API FileStream instances specify the use of overlapped I/O to the kernel via the
“useAsync” parameter similar to the following Listing 5.
Listing 5: Sample C# FileStream Constructor Definition Demonstrating the Use of the “useAsync”
Option
FileStream sourceStream = new FileStream(filePath, FileMode.Open, FileAccess.Read,
FileShare.Read, bufferSize: 4096, useAsync: true);
The highlighted “useAsync: true” named parameter in the FileStream constructor signals the I/O
operations executed against the FileStream instance to use overlapped I/O.
asynchronous database operations
Whenever possible, asynchronous database command execution and dataset processing is used. The
latest .NET 4.5 version introduced additional asynchronous methods to the ADO.NET20
implementation
including the ExecuteReaderAsync (executed against a DbDataReader
21
instance) and the
ExecuteNonQueryAsync method (executed against a DbCommand
22
instance). In addition, there are
column-level asynchronous methods added to DbDataReader23
.
Especially when considering the Microsoft SQL Server database engine backend required by Issuetrak
24
,
the use of asynchronous database methods offers an advantage of reducing the overhead of certain
ADO.NET operations by permitting the interaction with the underlying Tabular Data Stream (TDS) protocol
employed by Microsoft SQL Server in non-sequential mode. (Microsoft Corporation, 2012)
The performance profiling of the Issuetrak API codebase has offered insight into when asynchronous
database operations perform better than with synchronous, sequential access mode counterparts.
19
Overlapped I/O is also known as asynchronous I/O and refers to the signaling of the OS kernel to the calling thread that the
I/Ooperation is complete. See the MSDN article “Synchronous and Asynchronous I/O” at http://msdn.microsoft.com/en-
us/library/windows/desktop/aa365683%28v=vs.85%29.aspx for an overview.
20
ADO.NET: “ADO.NET provides consistent access to data sources such as SQL Server and XML, and to data sources exposed
through OLE DB and ODBC.” See the “ADO.NET Overview” MSDN article at: http://msdn.microsoft.com/en-
us/library/h43ks021%28v=vs.110%29.aspx
21
See the “DbDataReader Class” MSDN article at: http://msdn.microsoft.com/en-
us/library/system.data.common.dbdatareader%28v=vs.110%29.aspx
22
See the “DbCommand Class” MSDN article at: http://msdn.microsoft.com/en-
us/library/system.data.common.dbcommand%28v=vs.110%29.aspx
23
These asynchronous data functions are not just specific to the System.Data.SqlClient classes. For example, DbDataReader also
exposes column-level asynchronous methods such as “GetFieldValueAsync<T>”. Although Issuetrak is fundamentally a Microsoft
SQL Server-based software product, internally, data-layer abstractions are used to decouple the data layer interfaces from the
concrete implementations.
24
As of Issuetrak version 9.9, a Microsoft SQL Server 2008 R2 or later database engine is required.

task-based asynchronous patterns
Throughout the Issuetrak API codebase, task-based functional implementations have been developed to
consolidate business logic to allow both the implementation of compiler-generated internal methods via
the await operator and also the caching of frequently-used Task implementations. An example of this
type of implementation is the development of command classes where synchronous validation of
arguments must be verified before asynchronous operations in order to prevent validation exceptions
from being thrown from within the task.
This technique draws upon the “Hybrid”25
Task-based Asynchronous Pattern (TAP) presented by Microsoft
author Stephen Toub. (Toub, 2012, p. 9) in which a public method that returns a Task<T> result may
perform certain data operations (e.g., validation of parameters, logging, etc.) synchronously before calling
a private method marked within the async modifier. This type of TAP pattern is illustrated in Error!
Listing 6: Sample C# Pseudo code Illustrating the Hybrid TAP Pattern Employed within the
Issuetrak API
public Task<Object> OperateAsync(Object input)
{
// Validate the input (synchronously).
return OperateInternalAsync(input);
}
private async Task<Object> OperateInternalAsync(string input)
{
// Execute a Task using the await operator (asynchronously).
await MethodGeneratingTaskAsync(input);
}
25
Toub also discusses the “Compiler” and “Manual” TAP patterns in this paper.

transactional processing
He, who every morning plans the transactions of the day, and follows that plan, carries a thread that
will guide him through a labyrinth of the most busy life.
--Victor Hugo (Hugo, 1827)
ACID in transactions
Jim Gray, a former Technical Fellow at Microsoft26
and winner of the 1998 A.M. Turing Award27
, provided
an elegant and succinct description of a transaction in the abstract of his 1981 paper, “The Transaction
Concept: Virtues and Limitations”:
A transaction is a transformation of state which has the properties of atomicity
(all or nothing), durability (effects survive failures) and consistency (a correct
transformation). The transaction concept is key to the structuring of data
management applications. The concept may have applicability to programming
systems in general. (Gray, 1981)
Within this definition, there are listed three of the four properties that are commonly referred to in the
context of database theory as the ACID properties where “ACID” is a acronym for Atomicity, Consistency,
Isolation, and Durability. The Isolation property, relates to concurrency especially regarding the impact
that other concurrent transactions will have on the data undergoing transformation in the context of an
independent transaction.
Ken Henderson defined Isolation in this way:
A transaction is isolated if it neither is impacted nor impacts other concurrent
transactions on the same data. (Henderson, 2003, p. 500)
transaction management in the Issuetrak API
The Issuetrak API interacts with the transaction infrastructure using the
System.Transaction.TransactionScope
28
class to most fully utilize transaction management for both
database-oriented and file system-oriented transactions. Because the TransactionScope context can
transcend code operations that are purely database-oriented, the overall consistency of the application
data state in toto can be maintained when contrasted with transactions purely targeting the data store.
This type of consistency is perhaps illustrated best when considering the creation of a new attachment for
an Issue. Not only must the appropriate database resources be updated to indicate the relationship of
the new attachment to the existing Issue entity but also the binary data representing the attachment itself
must be stored29
. If only the attachment binary data were to be stored without the accompanying
26
See https://research.microsoft.com/en-us/people/gray/ and https://research.microsoft.com/en-us/um/people/gray/ for two web
pages at Microsoft Reserch for Jim Gray.
27
See http://amturing.acm.org/award_winners/gray_3649936.cfm for the complete A.M. Turing Award citation.
28
See http://msdn.microsoft.com/en-us/library/system.transactions.transactionscope%28v=vs.110%29.aspx for the MSDN
documentation on TransactionScope.
29
The question may be raised about this use case: “Why not use Transactional NTFS (TxF) for such purposes?” One answer to this
question is that the future of TxF is uncertain enough not to adopt its use in the Issuetrak API given that there are simpler, higher-
performing alternatives. Another answer to this question is that Microsoft, “…strongly recommends developers utilize alternative
means to achieve your application’s needs. Many scenarios that TxF was developed for can be achieved through simpler and more

database update or if only the database updates were to be performed without the accompanying file
system storage of the attachment binary data, the application’s data state as a whole would be
inconsistent.
The use of a transaction manager context that can cross over such data boundaries and that can provide
resources for ensuring the consistency and durability of all parts of the API data transaction. In addition,
by adopting TransactionScope use within the API, should Distributed Transactions be needed in future
scenarios, backwards compatibility with existing codebases is made easier. In addition, within the context
of an asynchronous operation, the use of TransactionScope with the correct
TransactionScopeAsyncFlowOption
30
option selected ensures that transaction flow across thread
continuations is supported, a functional process that was difficult to achieve before .NET Framework 4.5.1.
The Issuetrak API supports one of the highest transactional throughput rates of the Issuetrak software
product family. However, with high transactional volume brings the chance of deadlocks. It the example
of a deadlock that will serve a primary example within the next section, a discussion of the Exception
Handling within the Issuetrak API product.
exception handling
The progress of rivers to the ocean is not so rapid as that of man to error.
--Voltaire (Voltaire, 1764)
categorization of exceptions
Exceptions within the Issuetrak API solution may be categorized in two ways: those exceptions for which
in-application recovery is both possible and practical and those exceptions for which recovery is
impossible or impractical. One of the design goals for the Issuetrak API version was to ensure that not
only heroic efforts in the codebase were demonstrated in the course of handling the category of
recoverable exceptions but also that the chance of experiencing an unrecoverable exception is minimized.
Many unrecoverable exceptions can be prevented in the first place by intercepting bad data before an
illegal data transformation or data storage operation is attempted. This is the role of data validation, a
role that demands diligence across all of the application layers with a minimum of assumptions made
regarding the initial quality of the data. Beginning with the premise that data validation that does not
adequately explain the results to the API data consumer is a wasted exercise, the data validation code
within the Issuetrak API attempts to rigorously define which data members failed validation and why.
In addition, rather than returning piecemeal results, data validation results are returned in bulk with the
advantage to the API consumer being that all validation errors can be corrected before resubmission is
attempted.
readily available techniques. Furthermore, TxF may not be available in future versions of Microsoft Windows.”
(http://msdn.microsoft.com/en-us/library/windows/desktop/bb968806%28v=vs.85%29.aspx)
30
See the “TransactionScopeAsyncFlowOption Enumeration” MSDN article at: http://msdn.microsoft.com/en-
us/library/system.transactions.transactionscopeasyncflowoption%28v=vs.110%29.aspx

deadlocks as an example of a recoverable exceptions
As mentioned in the previous section on Transactional Processing, the handling of deadlock exceptions is
a prime example of attempting recovery on a potentially fatal exception within the context of an API
operation.
A deadlock is defined as an event that occurs when “…two or more tasks permanently block each other by
each task having a lock on a resource which the other tasks are trying to lock.” (Microsoft Corporation,
2014) The causes of deadlocks may include (but are not limited to) locks, worker threads, memory
contention, and parallel query execution. (Microsoft Corporation, 2014) As the degree of concurrency in
an application increases, the probability of a deadlock exception occurring increases although there are
certain best practices that can reduce the chances of such occurrences including the choices of different
database isolation levels.
Within the context of the Issuetrak API version, deadlock exceptions are intercepted as a special class of
recoverable exceptions, and the transaction that was chosen as the deadlock victim is resubmitted (still
within a transactional context) after a period time
31
. The time to wait before retrying the transaction is
determined using an random time between a minimum wait time and a maximum wait time derived from
exponential-backoff
32
formulas displayed in Error! Reference source not found..
Listing 7: Formulas Used to Calculate Exponential Back-off Times
Minimum Wait Time =
Maximum Wait Time =
Where “N” represents the retry count for the operation and “C” represents a minimum delay time that is
specified within an application configuration setting.
globalization
For an Apple is in itself a little Universe; the Seed, hotter than the other parts thereof, is
its Sun, which diffuses about itself that natural Heat which preserves its Globe: And in
the Onion, the Germ is the little Sun of that little World, which vivifies and nourishes the
vegetative Salt of that little mass.
--Cyrano de Bergerac (Bergerac, 1687)
Issuetrak software is used internationally by customers with business support service departments which
cross date boundaries and which communicate in a variety of languages. There are three areas of
Globalization support that the Issuetrak API version embraces: Language Resources, Datetime Encoding
Standards, and Response Encoding.
language resources
To support the use of the API in deployment scenarios where the data consumers of the API may not use
or recognize English as a primary language, the API has been developed with error messages and
31
See the “Retry Pattern” MSDN article at: http://msdn.microsoft.com/en-us/library/dn589788.aspx for an overview of the contexts
and problems for which retry recovery may be practical.
32
Exponential-backoff is one example of a retry policy. Linear retry policies and fixed time retry policies are two other examples that
are common in enterprise systems.

response text delivered from language resource files deployed as satellite assemblies. The particular
language resource to deliver in an API response is determined by inspecting the “Accept-Language”
33
header for the current HTTP request.
A typical “Accept-Language” header for an HTTP request originating from a consumer endpoint with US
English configured as the primary language is presented in Error! Reference source not found..
Listing 8: "Accept-Language" HTTP Header for US English Language Code
Accept-Language: en-US,en;q=0.5
According to the HTTP 1.1 specification for “Accept-Language”:
A request without any Accept-Language header field implies that the user agent will accept any
language in response. If the header field is present in a request and none of the available
representations for the response have a matching language tag, the origin server can either
disregard the header field by treating the response as if it is not subject to content negotiation or
honor the header field by sending a 406 (Not Acceptable) response. (Internet Engineering Task
Force (IETF) , 2014, p. sec 5.3.5)
Therefore, if no “Accept-Language” HTTP header is specified or if “en-US” is present in the list of acceptable
language codes with a q score > 0, the “en-US” (US English) resources are used by default.
The partitioning of the API language resources into satellite assemblies offers Issuetrak tremendous
flexibility in responding to client language needs. In addition to the satellite resource assemblies provided
in a default deployment, custom resource assemblies can be prepared as needed and deployed on-
demand.
date resources
Within the Issuetrak API, UTC dates are conveyed using ISO 860134
standards by default. The introduction
to the ISO 8601 overview outlines the usefulness of the standard noting:
The full standard covers ways to write:
 Date
 Time of day
 Coordinated universal time (UTC)
 Local time with offset to UTC
 Date and time
 Time intervals
 Recurring time intervals
(International Organization for Standardization, 2014)
33
See the “Accept-Language” HTTP header specification at: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4
34
From the ISO 8601 Standard overview: “ISO 8601 describes an internationally accepted way to represent dates and times using
numbers.”

ISO 8601 is a particularly crucial standard because in addition to providing a common encoding standard
for the myriad datetime standards available internationally, when JSON serialization is involved in
representing data objects with datetime data properties, an encoding standard is a necessity. As Scott
Hanselman noted in 2012 in a blog posting entitled, “On the nightmare that is JSON Dates.”:
Ints are easy. Strings are mostly easy. Dates? A nightmare. They always will be.
There's different calendars, different formats. Did you know it's 2004 in the
Ethiopian Calendar? Yakatit 26, 2004, in fact. I spoke to a German friend once
about how much 9/11 affected me and he said, "yes, November 9th was an
amazing day in Germany, also."
Dates are hard.
(Hanselman, 2012)
By choosing the ISO 8601 standard for representing datetime values, the Issuetrak API embraces the
encoding standard supported by an abundance of recognized JSON experts including James Newton- King,
the author of the Newtonsoft JSON.NET library
35
.
response encoding
The general release of the Issuetrak application provided an oft-requested feature: the ability to define an
unlimited number of user-defined fields. In addition to increasing the number of user-defined fields that
can be defined, Issuetrak user-defined fields store text data using Unicode character set representations.
This permits Issuetrak data consumers to store non-ASCII characters within user-defined fields.
Internally, the Issuetrak API translates the Unicode characters representing character data to be delivered
as API responses using the UTF-8
36
encoding standard by default. However, the desired response
encoding can be changed via the “Content-Type” HTTP header.
For example, by specifying a “Content-Type” HTTP header such as in Error! Reference source not
found.,
Listing 9: Sample "Content-Type" HTTP Header for UTF-16 Encoding
Content-Type: application/json; charset=utf-16
then the API response will be encoded using the UTF-1637
encoding standard instead of the default UTF-8
standard. Although the choice of different encoding standards may increase the response size, the
flexibility of choosing an encoding offers that API consumer an additional tool to ease integration of the
API with either legacy software systems or additional external APIs.
35
See the March 4, 2012, GitHub code header for the JSON.NET library at:
https://github.com/JamesNK/Newtonsoft.Json/commit/fd760e33898cc6b3badaf4a8b77a466139b87fac
36
See the “UTF-8” Wikipedia article at: https://en.wikipedia.org/wiki/UTF-8
37
See the “UTF-16” Wikipedia article at: https://en.wikipedia.org/wiki/UTF-16

ii: API developer-oriented resources
overview
APIs are only as useful as the development projects that they support. Since APIs typically focus on
shuttling data into and out of a software system often with more efficiency and determinism than data
interactions that proceed through a user interface, the degree to which the API producer provides tools
and insight into how best to utilize the API will often drive the adoption rate and perceived utility of the
API.
One of the core goals during the development of the Issuetrak API was to provide a set of tools to support
the rapid adoption of the API for external data consumption.
Swagger™ ui integration
So soon as ever thou seest him, draw, and as thou drawest, swear horrible; for it comes
to pass oft that a terrible oath, with a swaggering accent sharply twanged off, gives
manhood more approbation than ever proof itself would have earned him. Away!
--William Shakespeare (Shakespeare, 1601)
overview of the Swagger™ specification
The Swagger™ specification and framework was borne of the Wordnik38
application, an application that
displays definitions for words from a variety of lexicons. To support the Wordnik API and developer
documentation system, Wordnik developers began the development of the Swagger™ framework in 2010.
The stated goal of the Swagger™ framework is “define a standard, language-agnostic interface to REST
APIs which allows both humans and computers to discover and understand the capabilities of the service
without access to source code, documentation, or through network traffic inspection.” (Reverb, 2014)
swagger implementation within the Issuetrak API
To support the documentation and demo needs of the Issuetrak API, the Swagger™ framework has not
only been integrated into the core API solution but also extended to allow for the customization of the
documentation resources that are presented within the Swagger™ UI. The extensions provide a link
between the codebase and the Swagger UI via a customized set of class metadata applied via code
attributes to the appropriate class members and a customized set of formatters that enable the Swagger
framework to read these metadata to build the UI. This UI creation occurs dynamically without any effort
required on the part of either the developer or the server administrator. A screenshot of the Swagger™
API web page is shown in Error! Reference source not found..
38
See the Wordnik application “About” page at: https://www.wordnik.com/about

Screenshot 1: Sample Swagger™ UI for Issuetrak API Version 1
The API controller endpoints represent accordion panels that can be expanded or collapsed. For example,
clicking on the “Notes” controller endpoint displays the operations for the “Notes” controller endpoint as
depicted in Error! Reference source not found..
Screenshot 2: "Notes" API Operations Expanded in the Swagger™ UI
Each of the API endpoint operations may then be further expanded to display the model data type,
parameter listing, and a sample API operation testing form just as shown in Error! Reference source
not found..

Screenshot 3: The "CreateNote" API Operation Panel Expanded in the Swagger™ UI
logging
Is not the poet bound to write his own biography? Is there any other work for him but a good journal?
We do not wish to know how his imaginary hero, but how he, the actual hero, lived from day to day.
--Henry David Thoreau (Thoreau, 1906, p. 115)
general logging
The presence of data logging serves to decrease the opacity of a production system by allowing the
inspection of the details of execution in what is primarily an non-visual system. Effective logging is

configurable to permit the capture of application events with sufficient granularity to allow for post-
operation analysis while also permitting the targeting of different logging media from simple text files to
databases to e-mail messages.
There are several robust logging modules available for integration with modern .NET Framework
applications including two open-source projects: log4net
39
and NLog. The Issuetrak API solution utilizes
the NLog module but with an additional abstraction layer to prevent the strong coupling to any particular
logging system.
Via the logging configuration multiple logging targets can be defined for various classes and error levels.
The rich logging configuration capabilities allow on-demand reconfiguration as well as the redirection of
log output to targets as diverse as file systems, databases, and e-mail messages.
For example, consider the NLog targets defined using the NLog configuration schema in Error!
Listing 10: Example NLog API Logging Targets
<target
name="Issuetrak.API.ErrorLogging.Target.File"
xsi:type="File"
archiveAboveSize="1000000"
maxArchiveFiles="9"
fileName="${basedir}/App_Data/Logs/Issuetrak.API.ErrorLogging.txt" />
<target
name="Issuetrak.API.ErrorLogging.Target.SMTP"
xsi:type="Mail"
html="true"
addNewLines="true"
subject="Issuetrak.API.ErrorLogging Error on ${machinename}"
to="errors@Issuetrak.com"
from="<SMTP-Account-Username>"
smtpServer="<SMTP-Server-Address>" />
The same logging information can be piped to one or more targets, and the targets and other logging
configuration are fully controllable via the logging configuration files without requiring recompilation or
reinstallation of the Issuetrak API application.
on-demand request logging
In addition to the general logging mechanism, on-demand request logging can be enabled for any API
operation by appending a special query string to an API request. Consider the POST request to create an
issue specified in Listing 11.
Listing 11: Sample Request Logging Example URL
POST /v1/issues?loggingEnabled=true&logFileID=-8c9e7382-8424-4831-9868-
9115f92e0a8e&requestSummary=true&stackTraceSummary=true
39
Log4net is now part of the “Apache Logging Services Project”: http://logging.apache.org/

The loggingEnabled querystring parameter instructs the API controller endpoint to enable logging for the
request. The logFileID specifies a unique request log ID to be included in the logging summary. The
requestSummary and stackTraceSummary parameters specify that a summary of the current request and
the current request’s stack trace should be included in the request summary. A sample of an on-demand
request log is presented in Appendix 1.
data serialization
But as this rarely happens, in such infinite Series as generally occur, we must have
recourfe to infinite converging Series wherein this Supplement, as well as the Terms of
the Series, are infinitely diminifh'd; and therefore after a competent number of them
are collected, the reft may be all neglected in infinitum.
--Sir Isaac Newton (Newton, 1736, p. 154)
40
overview
Modern APIs heavily leverage the data transformation techniques that underlie data serialization, and, in
contrast to past API frameworks and technologies, to limit an API consumer to just one data serialization
technology is to act in a manner that is less than refined bordering on discourteous.
Consider the life of a particular datum, an issue number, say, delivered as part of the response to an API
request to retrieve an Issue by issue number. This 32-byte integer will be transformed across a number of
application boundaries, but, to ensure the accuracy of the data delivered via the API response, the fidelity
of each data transformation is of crucial importance. The integer will have one particular binary
representation within the application database, a second binary representation when queried and stored
in the RAM of the API’s application during processing, and a third text representation when serialized for
delivery as the HTTP response to the API HTTP request. Yet, across all of these transformations, the
fidelity of the integer must be preserved in order for the response to accurately reflect the state of the
data representing the requested entity.
implementation of serialization within the Issuetrak API
As deployed, the Issuetrak API supports both XML and JSON serialization. The serialization can changed
on a per-request basis merely by altering the “Accept” HTTP header. Listing 12 illustrates an HTTP “Accept”
header configured for a JSON response.
Listing 12: A Sample "Accept" HTTP Header for a JSON Response
Accept: application/json41
For an API call to the following endpoint URL: http://local.Issuetrakapi.com /v1/notes/102 with the
“application/json” Accept header specified, the JSON-serialized response in Listing 13 is returned.
40
Sir Isaac Newton’s observations from the “The Method of Fluxions and Infinite Series” were translated from the original Latin
monograph and published in an English version in 1736 (NB: the inconsistency in the use of the letter “s” within the quote). Newton’s
development of the differential calculus had much to say about infinite series, and it is this concept of sequenced elements
contributing to the summarizing description (“serialization”) of an entity that relates to the choice of this quote. The etymology of the
word “series” is also interesting. From Merriam-Webster’s online dictionary: “Latin, from serere to join, link together; akin to Greek
eirein to string together, hormos chain, necklace, and perhaps to Latin sort-, sors lot First Known Use: 1611” (http://www.merriam-
webster.com/dictionary/series)
41
Also acceptable as “Accept” HTTP header values to specify JSON serialization is: text/json.

Listing 13: Sample JSON-Serialized API Response
{
"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
}
Listing 14 illustrates an HTTP “Accept” header configured for an XML response.
Listing 14: A Sample "Accept" HTTP Header for an XML Response
Accept: text/xml42
For an API call to the following endpoint URL: http://local.Issuetrakapi.com /v1/notes/102 with the
“text/xml” Accept header specified, the XML-serialized response in Listing 15 is returned.
Listing 15: Sample XML-Serialized API Response
<ReadNoteDTO xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://schemas.datacontract.org/2004/07/Issuetrak.DataModels.D
TOs">
<IsPrivate>true</IsPrivate>
<IsRichText>true</IsRichText>
<NoteText>What I've done</NoteText>
<CreatedBy>Admin</CreatedBy>
<CreatedDate>2011-06-22T18:55:30.47</CreatedDate>
<IssueNumber>1</IssueNumber>
<ModifiedBy>Admin</ModifiedBy>
<ModifiedDate>2014-08-22T12:11:30.063</ModifiedDate>
<NoteID>102</NoteID>
</ReadNoteDTO>
These serialization control headers can be mixed with the encoding control headers discussed previously
to enable, for example, a JSON serialization using a UTF-16 text encoding.
42
Also acceptable as “Accept” HTTP header values to specify XML serialization is: application/xml.

exception management
No man's error becomes his own Law; nor obliges him to persist in it.
--Thomas Hobbes (Hobbes, 1839, p. 264)
overview
When an error happens, the reconstruction of the events that led to the error are of crucial importance
not just in the recovery for the particular case of the error at hand but also in the general case of
identifying a set of error conditions that indicates a negative trend or a degradation in some system or
internal service.
ELMAH integration
To support the effective management of exceptions, when an exception is deemed unrecoverable,
detailed logging helps to ensure that the cause of the exception can be reliably identified and reproduced.
The Error Logging Modules and Handlers for ASP.NET (ELMAH)
43
module is integrated within the Issuetrak
API version for this purpose and is configurable to store exception information within a variety of
persistent storage media including file logs or error-logging databases. These exception management
configuration options are configurable at time of deployment to meet a variety of deployment scenarios
and include a file-based database logging option where an additional RDBMS database cannot be
dedicated to the application’s exception management.
Logging to both the general-purpose logging component and to ELMAH occurs within the context of a
global exception handler for the API. By including this centralized exception handler, not only can the
fullest stack trace corresponding to the exception be retrieved but also post-exception cleanup activities
can be consolidated. A sample ELMAH error log entry is presented in Screenshot 4 with logging
configured to a testing SQLite44
database.
Screenshot 4: Sample ELMAH Error Log Entry for an Issuetrak API Exception
43
See the ELMAH project website at: https://code.google.com/p/elmah/
44
SQLite is a zero-configuration, self-contained database engine. See http://www.sqlite.org/ for more information.

iii: conclusions
business benefits
In conclusion, the Issuetrak API offers high transactional throughput, advanced Globalization features,
multiple serialization and encoding standard, and developer-oriented tools designed to ease integration
burdens.
resources
To learn more about the benefits of the Issuetrak API within the context of an Issuetrak installation,
explore the benefits of Issuetrak software at Issuetrak.com.

works cited
Anderson, C. (2012, April 24). The Man Who Makes the Future: Wired Icon Marc Andreessen | Business |
WIRED. Retrieved 07 31, 2014, from wired.com Website:
http://www.wired.com/2012/04/ff_andreessen/all/1
Bergerac, C. d. (1687). A Voyage to the Moon - Cyrano de Bergerac, Archibald Lovell, Curtis Hidden Page -
Google Books. Retrieved August 20, 2014, from Google Books Website:
http://books.google.com/books?id=OdlHAAAAIAAJ
Fielding, R. T. (2000). Architectural Styles and the Design of Network-based Software Architectures. Retrieved
August 20, 2014, from University of California, Irvine Website:
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
Fielding, R. T. (2008, October 20). REST APIs must be hypertext-driven » Untangled. Retrieved August 20, 2014,
from Untangled "musings of Roy T. Fielding" Website: http://roy.gbiv.com/untangled/2008/rest-apis-must-
be-hypertext-driven
Fowler, M. (2010, March 18). Richardson Maturity Model. Retrieved August 20, 2014, from Martin Fowler
Website: http://martinfowler.com/articles/richardsonMaturityModel.html
Gray, J. (1981, June). The Transaction Concept: Virtues and Limitations. Retrieved September 3, 2014, from
Microsoft Research Website: http://research.microsoft.com/en-
us/um/people/gray/papers/theTransactionConcept.pdf
Hanselman, S. (2012, March 6). On the nightmare that is JSON Dates. Plus, JSON.NET and ASP.NET Web API -
Scott Hanselman:. Retrieved September 14, 2014, from Scott Hanselman Blog Website:
http://www.hanselman.com/blog/OnTheNightmareThatIsJSONDatesPlusJSONNETAndASPNETWebAPI.aspx
Henderson, K. (2003). The Guru's Guide to SQL Server Architecture and Internals. Boston: Addison Wesley.
Hobbes, T. (1839). The English Works of Thomas Hobbes of Malmesbury, Volume 3. (S. W. Molesworth, Ed.)
Retrieved August 20, 2014, from Google Books Website:
http://books.google.com/books?id=kLh8HU5ByX0C
Hugo, V. (1827). Murray's English Reader ...: Vocabulary ... - Lindley Murray - Google Books. Retrieved August
20, 2014, from Google Books Website: http://books.google.com/books?id=x64AAAAAYAA
International Organization for Standardization. (2014, September 8). ISO 8601 Standard. Retrieved
September 15, 2014, from International Organization for Standardization Website:
http://www.iso.org/iso/home/standards/iso8601.htm
Internet Engineering Task Force (IETF) . (2014, June). Hypertext Transfer Protocol (HTTP/1.1): Message Syntax
and Routing. Retrieved August 20, 2014, from RFC 7230 - Hypertext Transfer Protocol (HTTP/1.1): Message
Syntax and Routing: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1

Microsoft Corporation. (2014, August 22). Detecting and Ending Deadlocks. Retrieved September 15, 2014,
from Microsoft Technet Website: http://technet.microsoft.com/en-us/library/ms178104(v=sql.105).aspx
Microsoft Corporation. (2014, September 15). FileStream.IsAsync Property. Retrieved September 15, 2014,
from Microsoft Development Network Website: http://msdn.microsoft.com/en-
us/library/system.io.filestream.isasync(v=vs.110).aspx
Microsoft Corporation. (2014, August 22). Task Parallel Library (TPL). Retrieved September 3, 2014, from
Microsoft Developer Network Website: http://msdn.microsoft.com/en-us/library/dd460717(v=vs.110).aspx
Microsoft Corporation. (2012, April 20). Using SqlDataReader’s new async methods in .Net 4.5 - ADO.NET Blog -
Site Home - MSDN Blogs:. Retrieved September 15, 2014, from Microsoft MSDN Blogs Website:
http://blogs.msdn.com/b/adonet/archive/2012/04/20/using-sqldatareader-s-new-async-methods-in-net-4-
5-beta.aspx
Newton, S. I. (1736). The Method of Fluxions and Infinite Series: With Its Application to the ... - Sir Isaac Newton -
Google Books. (J. Colson, Ed.) Retrieved August 20, 2014, from Google Books Website:
http://books.google.com/books?id=WyQOAAAAQAAJ
Penn, W. (1682). Some Fruits of Solitude - William Penn - Google Books. Retrieved August 20, 2014, from
Googe Books Website: http://books.google.com/books?id=zeKyiZFuxVgC
Reverb. (2014, September 3). Home · wordnik/swagger-spec Wiki · GitHub:. Retrieved September 3, 2014,
from GitHub Website: https://github.com/wordnik/swagger-spec/wiki
Richter, J. (2012). CLR via C#, Fourth Edition. Redmond: Microsoft Press.
Shakespeare, W. (1601). Twelfth Night - William Shakespeare - Google Books. Retrieved August 20, 2014, from
Google Books Website: http://books.google.com/books?id=m-mu3Vw-EiUC
Thoreau, H. D. (1906). Journal - Henry David Thoreau, Franklin Benjamin Sanborn, Bradford Torrey - Google
Books. Retrieved August 2014, 2014, from Google Books Website:
http://books.google.com/books?id=6IJKAAAAYAAJ
Toub, S. (2012, February 29). Task-based Asynchronous Pattern . Retrieved September 10, 2014, from
Microsoft Web Site: http://www.microsoft.com/en-us/download/details.aspx?id=19957
U.S. National Library of Medicine. (2002, September 16). Greek Medicine - The Hippocratic Oath. Retrieved
August 20, 2014, from National Library of Medicine Website:
http://www.nlm.nih.gov/hmd/greek/greek_oath.html
Voltaire, M. D. (1764). A Philosophical Dictionary - Voltaire, John G. Gorton - Google Books. (J. G. Gorton, Ed.)
Retrieved August 20, 2014, from Google Books Website: http://books.google.com/books?id=I3INAAAAYAAJ

World Wide Web Consortium. (2004, September 01). HTTP/1.1: Header Field Definitions. Retrieved August
20, 2014, from World Wide Web Consortium (W3C) Website:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
World Wide Web Consortium. (2007, April 27). SOAP Version 1.2 Part 0: Primer (Second Edition). Retrieved
August 21, 2014, from World Wide Web Consortium (W3C) Website: http://www.w3.org/TR/2007/REC-
soap12-part0-20070427/

Appendix 1: On Demand Request Logging Output Text Sample (Excerpt)
2014-09-15 14:03:21.9772|DEBUG|Issuetrak.API.RequestLogging|OnActionExecuting: /v1/issues
=====================================================
Stack Trace Summary:
=====================================================
at Issuetrak.WebAPI.Infrastructure.RequestLogging.GenerateStackTraceSummary(StringBuilder summary)
at Issuetrak.WebAPI.Infrastructure.RequestLogging.WriteToRequestLog(ILog logger, Func`1 logMessageFormatter, Boolean
forceLogging)
at Issuetrak.WebAPI.Infrastructure.RequestLogging.OnActionExecuting(HttpActionContext filterContext)
at System.Web.Http.Filters.ActionFilterAttribute.OnActionExecutingAsync(HttpActionContext actionContext, CancellationToken
cancellationToken)
at System.Web.Http.Filters.ActionFilterAttribute.<ExecuteActionFilterAsyncCore>d__0.MoveNext()
at System.Runtime.CompilerServices.AsyncMethodBuilderCore.Start[TStateMachine](TStateMachine& stateMachine)
at System.Web.Http.Filters.ActionFilterAttribute.ExecuteActionFilterAsyncCore(HttpActionContext actionContext, CancellationToken
cancellationToken, Func`1 continuation)
at System.Web.Http.Controllers.ActionFilterResult.<>c__DisplayClassb.<>c__DisplayClassd.<InvokeActionWithActionFilters>b__9()
at System.Web.Http.Controllers.ActionFilterResult.<ExecuteAsync>d__2.MoveNext()
at System.Web.Http.Controllers.ActionFilterResult.ExecuteAsync(CancellationToken cancellationToken)
at System.Web.Http.Controllers.AuthorizationFilterResult.<>c__DisplayClass4.<ExecuteAsync>b__0()
at System.Web.Http.Filters.AuthorizationFilterAttribute.<ExecuteAuthorizationFilterAsyncCore>d__2.MoveNext()
at System.Web.Http.Filters.AuthorizationFilterAttribute.ExecuteAuthorizationFilterAsyncCore(HttpActionContext actionContext,
CancellationToken cancellationToken, Func`1 continuation)
at System.Web.Http.Controllers.AuthorizationFilterResult.<>c__DisplayClass4.<>c__DisplayClass6.<ExecuteAsync>b__2()
at System.Web.Http.Controllers.AuthorizationFilterResult.ExecuteAsync(CancellationToken cancellationToken)
at System.Web.Http.Dispatcher.HttpControllerDispatcher.<SendAsync>d__1.MoveNext()
at System.Web.Http.Dispatcher.HttpControllerDispatcher.SendAsync(HttpRequestMessage request, CancellationToken
cancellationToken)
at System.Net.Http.HttpMessageInvoker.SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
at System.Web.Http.Dispatcher.HttpRoutingDispatcher.SendAsync(HttpRequestMessage request, CancellationToken
cancellationToken)
at Issuetrak.WebAPI.UserExecutionContextValidationHandler.<>n__FabricatedMethod6(HttpRequestMessage , CancellationToken )
at Issuetrak.WebAPI.UserExecutionContextValidationHandler.<SendAsync>d__2.MoveNext()
at Issuetrak.WebAPI.UserExecutionContextValidationHandler.SendAsync(HttpRequestMessage request, CancellationToken
cancellationToken)
at System.Web.Http.HttpServer.<SendAsync>d__0.MoveNext()
at System.Web.Http.HttpServer.SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
at System.Net.Http.HttpMessageInvoker.SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
at System.Web.Http.WebHost.HttpControllerHandler.<ProcessRequestAsyncCore>d__0.MoveNext()
at System.Web.Http.WebHost.HttpControllerHandler.ProcessRequestAsyncCore(HttpContextBase contextBase)
at System.Web.TaskAsyncHelper.BeginTask(Func`1 taskFunc, AsyncCallback callback, Object state)
at System.Web.HttpApplication.CallHandlerExecutionStep.System.Web.HttpApplication.IExecutionStep.Execute()
at System.Web.HttpApplication.ExecuteStep(IExecutionStep step, Boolean& completedSynchronously)
at System.Web.HttpApplication.PipelineStepManager.ResumeSteps(Exception error)
at System.Web.HttpApplication.BeginProcessRequestNotification(HttpContext context, AsyncCallback cb)
at System.Web.HttpRuntime.ProcessRequestNotificationPrivate(IIS7WorkerRequest wr, HttpContext context)
at System.Web.Hosting.PipelineRuntime.ProcessRequestNotificationHelper(IntPtr rootedObjectsPointer, IntPtr
nativeRequestContext, IntPtr moduleData, Int32 flags)
at System.Web.Hosting.PipelineRuntime.ProcessRequestNotification(IntPtr rootedObjectsPointer, IntPtr nativeRequestContext, IntPtr
moduleData, Int32 flags)
at System.Web.Hosting.UnsafeIISMethods.MgdIndicateCompletion(IntPtr pHandler, RequestNotificationStatus& notificationStatus)

at System.Web.Hosting.UnsafeIISMethods.MgdIndicateCompletion(IntPtr pHandler, RequestNotificationStatus& notificationStatus)
at System.Web.Hosting.PipelineRuntime.ProcessRequestNotificationHelper(IntPtr rootedObjectsPointer, IntPtr
nativeRequestContext, IntPtr moduleData, Int32 flags)
at System.Web.Hosting.PipelineRuntime.ProcessRequestNotification(IntPtr rootedObjectsPointer, IntPtr nativeRequestContext, IntPtr
moduleData, Int32 flags)
=====================================================
Querystring Summary [Key = Value]:
=====================================================
[loggingEnabled, true]
[logFileID, -8c9e7382-8424-4831-9868-9115f92e0a8e]
[requestSummary, true]
[stackTraceSummary, true]
=====================================================
Form Summary [Key = Value]:
=====================================================
=====================================================
Cookies Summary [Key = Value]:
=====================================================
=====================================================
Server Variable Summary Key = Value:
=====================================================
ALL_HTTP = HTTP_CONNECTION:Keep-Alive
HTTP_CONTENT_LENGTH:572
HTTP_CONTENT_TYPE:application/json; charset=utf-8
HTTP_ACCEPT:application/json
HTTP_ACCEPT_LANGUAGE:en-US
HTTP_EXPECT:100-continue
HTTP_HOST:local.Issuetrakapi.com
HTTP_X_ISSUETRAK_API_REQUEST_ID:c7d0b360-fb6c-4d89-a369-23497990102f
HTTP_X_ISSUETRAK_API_TIMESTAMP:2014-09-15T18:02:51.8642303Z
HTTP_X_ISSUETRAK_API_AUTHORIZATION:uLEoFVOyNL6OGAJ+0RkEEgDUQ6Pp2Gj4tOqGRlMLDfS9FNn4bU0B9IZXFVzOwWz7okrDSt1
gnh4gKGdoAbsOLw==
ALL_RAW = Connection: Keep-Alive
Content-Length: 572
Content-Type: application/json; charset=utf-8
Accept: application/json
Accept-Language: en-US
Expect: 100-continue
Host: local.Issuetrakapi.com
X-Issuetrak-API-Request-ID: c7d0b360-fb6c-4d89-a369-23497990102f
X-Issuetrak-API-Timestamp: 2014-09-15T18:02:51.8642303Z
X-Issuetrak-API-Authorization:
uLEoFVOyNL6OGAJ+0RkEEgDUQ6Pp2Gj4tOqGRlMLDfS9FNn4bU0B9IZXFVzOwWz7okrDSt1gnh4gKGdoAbsOLw==
APPL_MD_PATH = /LM/W3SVC/9/ROOT
APPL_PHYSICAL_PATH = C:Software-ProjectsSourceReposIssuetrak APIIssuetrak.APIIssuetrak.WebAPI
AUTH_TYPE =
AUTH_USER =
AUTH_PASSWORD =
LOGON_USER =
REMOTE_USER =
CERT_COOKIE =
CERT_FLAGS =
CERT_ISSUER =
CERT_KEYSIZE =
CERT_SECRETKEYSIZE =

CERT_SERIALNUMBER =
CERT_SERVER_ISSUER =
CERT_SERVER_SUBJECT =
CERT_SUBJECT =
CONTENT_LENGTH = 572
CONTENT_TYPE = application/json; charset=utf-8
GATEWAY_INTERFACE = CGI/1.1
HTTPS = off
HTTPS_KEYSIZE =
HTTPS_SECRETKEYSIZE =
HTTPS_SERVER_ISSUER =
HTTPS_SERVER_SUBJECT =
INSTANCE_ID = 9
INSTANCE_META_PATH = /LM/W3SVC/9
LOCAL_ADDR = 127.0.0.1
PATH_INFO = /v1/issues
PATH_TRANSLATED = C:Software-ProjectsSourceReposIssuetrak APIIssuetrak.APIIssuetrak.WebAPIv1issues
QUERY_STRING = loggingEnabled=true&logFileID=-8c9e7382-8424-4831-9868-
9115f92e0a8e&requestSummary=true&stackTraceSummary=true
REMOTE_ADDR = 127.0.0.1
REMOTE_HOST = 127.0.0.1
REMOTE_PORT = 57502
REQUEST_METHOD = POST
SCRIPT_NAME = /v1/issues
SERVER_NAME = local.Issuetrakapi.com
SERVER_PORT = 80
SERVER_PORT_SECURE = 0
SERVER_PROTOCOL = HTTP/1.1
SERVER_SOFTWARE = Microsoft-IIS/7.5
URL = /v1/issues
HTTP_CONNECTION = Keep-Alive
HTTP_CONTENT_LENGTH = 572
HTTP_CONTENT_TYPE = application/json; charset=utf-8
HTTP_ACCEPT = application/json
HTTP_ACCEPT_LANGUAGE = en-US
HTTP_EXPECT = 100-continue
HTTP_HOST = local.Issuetrakapi.com
HTTP_X_ISSUETRAK_API_REQUEST_ID = c7d0b360-fb6c-4d89-a369-23497990102f
HTTP_X_ISSUETRAK_API_TIMESTAMP = 2014-09-15T18:02:51.8642303Z
HTTP_X_ISSUETRAK_API_AUTHORIZATION =
uLEoFVOyNL6OGAJ+0RkEEgDUQ6Pp2Gj4tOqGRlMLDfS9FNn4bU0B9IZXFVzOwWz7okrDSt1gnh4gKGdoAbsOLw==

Issuetrak API

More Related Content

Viewers also liked

Similar to Issuetrak API

Recently uploaded

Issuetrak API