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 SOAP1-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 JSON2 or XML3,

versioning support, and advanced resources

support via technologies such as asynchronous

processing.

In modern web APIs, SOAP-based service APIs have

been supplanted by REST4ful APIs because the

complexity of the conventions and services

implemented by SOAP including WS-Security5, WS-

AtomicTransaction6, and WS-ReliableMessaging7 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 header11 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 HATEOAS12 (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 projects13 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/O14 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 DbDataReader21 instance) and the

ExecuteNonQueryAsync method (executed against a DbCommand22 instance). In addition, there are

column-level asynchronous methods added to DbDataReader23.

Especially when considering the Microsoft SQL Server database engine backend required by Issuetrak24,

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! Reference source not found..

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.TransactionScope28 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

TransactionScopeAsyncFlowOption30 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 time31. 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-backoff32 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 library35.

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-836 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: log4net39 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! Reference source not found..

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 serial ization 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.Runtime.CompilerServices.AsyncMethodBuilderCore.Start[TStateMachine](TStateMachine& stateMachine)

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.Runtime.CompilerServices.AsyncMethodBuilderCore.Start[TStateMachine](TStateMachine& stateMachine)

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.Runtime.CompilerServices.AsyncMethodBuilderCore.Start[TStateMachine](TStateMachine& stateMachine)

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 System.Runtime.CompilerServices.AsyncMethodBuilderCore.Start[TStateMachine](TStateMachine& stateMachine)

at Issuetrak.WebAPI.UserExecutionContextValidationHandler.SendAsync(HttpRequestMessage request, CancellationToken

cancellationToken)

at System.Web.Http.HttpServer.<SendAsync>d__0.MoveNext()

at System.Runtime.CompilerServices.AsyncMethodBuilderCore.Start[TStateMachine](TStateMachine& stateMachine)

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.Runtime.CompilerServices.AsyncMethodBuilderCore.Start[TStateMachine](TStateMachine& stateMachine)

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-Projects\Source\Repos\Issuetrak API\Issuetrak.API\Issuetrak.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-Projects\Source\Repos\Issuetrak API\Issuetrak.API\Issuetrak.WebAPI\v1\issues

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==