A Web-Services API for a Government Procurement Application file:///C:/home/post-transfer/ws-api-paper.

html

A Web-Services API for a Government

Procurement Application
Opening the Next Generation of Procurement Desktop--Defense
Keywords: Architecture , Web Services , Enterprise Application Integration , XML , Open API , Public
API , Representational State Transfer , REST

Al Gough
Vice President
AMS, Inc.
Public Sector Group
Fairfax
VA
USA
al.gough@ams.com
www.ams.com

Biography

Al Gough is Strategic Architect for AMS's Public Sector Group (PSG), a member of the
Office of Digital Government & Technology. He has served as the CTO for the Federal
Defense Group prior to the formation of a single PSG for AMS, and is a member of AMS's
CTO Council. AMS delivers e-Government solutions to all levels of Government, from
counties and states to Federal Civilian Agencies to the U.S. Department of Defense (DoD)
and related Defense. AMS acquisition and procurement related initiatives include the
Standard Procurement System (SPS), a 10-year, $300M+ program to provide a single,
standard commercial procurement product for 42,000 users at over 900 sites across the
entire Department of Defense. AMS has developed a number of strategic alliances to deliver
Digital Government solutions with companies such as webMethods, Sybase, and BEA. His
strategic architecture for the next generation effort specified the inclusion of a Public API
based on open standards, leading to this design effort.

Kevin Mitchell
Chief Architect
Agogo Networks
Vienna,
VA
USA
kmitchell11@cox.net

Biography

Mr. Mitchell is a technologist with 9 years experience in architecture, design and

development of object-oriented enterprise and commercial applications and systems
integration. He has direct exposure to client/server, n-tier and web application architectures

1 of 10 4/12/2011 2:50 PM
A Web-Services API for a Government Procurement Application file:///C:/home/post-transfer/ws-api-paper.html

and B2B/EAI integration utilizing web services, XML and commercial integration products.
Mr. Mitchell has industry experience in acquisition/procurement, mortgage secondary
markets and telecom verticals. Mr. Mitchell has participated in the W3C XML Protocol
Working Group, the Apache SOAP effort, and has authored a binding of WfXML to SOAP.
He has been the principal architect of the Public API discussed in this paper.

Abstract

AMS’s PowerBuilder-based client/server application, Procurement Desktop--Defense™, (PD²) is the

basis of the Department of Defense’s Standard Procurement System. In developing the next generation
of the AMS application, PDe, an n-tier, web-based J2EE system, AMS decided to provide a Public API
to the business logic tier, and to extend delivery of XML-based documents and transactions to this API,
leveraging past experience with XML in Government acquisition.

The Public API offers a comprehensive open programmatic interface suitable for integrating PDe with
other enterprise applications. It’s goals are to move from a tightly coupled, multi-point integration
approach and to meet the market need for integration choice—the power to choose how, and by whom,
integration is accomplished. This paper presents an architectural model for the Public API. It describes
components that accept API requests, carry out operations based on those requests, and provide
appropriate responses.

The Public API is web services oriented, accessible to clients over standard protocols such as HTTP and
SSL, and represents business entities using an XML vocabulary. Web services efforts heretofore have
focused primarily on exposing RPC-like services, arguably unnecessarily complicating the task at hand.
Rather than an RPC style, the Public API uses the Representational State Transfer, or REST, style, a
formalization of the architecture of the Web. In REST, things of interest are made available as resources
with specific URL’s, and manipulated using basic HTTP methods: POST, GET, PUT and DELETE. The
REST style calls for a large number of resources and a small number of methods, and leverages HTTP
infrastructure, including caches, global content delivery systems, firewalls, and server log analyzers.

Following the REST style, PDe entities such as purchase requests, awards and line items are, like Web
pages, given URL’s. API clients will use HTTP methods to create, select, update and delete these
entities, which are represented using an XML vocabulary based on the existing client/server PD²
vocabulary, extended to incorporate PDe information and constructs described by this architecture and
XML standards—XML Namespaces, XML Base, XLink, XPointer and XInclude. To interact with the
Public API requires only a platform capable of TCP/IP communication (to send HTTP messages) and
string processing (to process XML).

The Public API is internationalized, accepting documents with international content and producing
Unicode content. It is firmly rooted in stable industry standards, using no home-grown or experimental
alternatives. It is implemented on the J2EE platform, using the same J2EE version as PDe business
logic—these two components can, though they need not, share a single execution environment, thereby
increasing performance and reducing network traffic and easing system administration These constraints
accelerate development, increase the potential for reuse of developers and resources across projects.
The Public API authenticates and authorizes requests against the PDe user base and ACLs, transparently

2 of 10 4/12/2011 2:50 PM
A Web-Services API for a Government Procurement Application file:///C:/home/post-transfer/ws-api-paper.html

applying the PDe security model to Public API clients. Communications with the Public API are made
confidential and safe through the use of HTTPS.

Internally, the PDe Public API is structured in two layers: a base layer and an application layer. The base
layer provides building blocks that can technically be used to create API’s for other AMS J2EE
applications. The application layer provides application-specific refinements to the base layer to create a
specific application’s Public API, as with PDe.

Table of Contents

1. Introduction
2. Architectural Goals for the Public API
3. An Integration and API View of the Architecture
4. Web Services Foundation
5. The REST Architectural Style
6. The XML Provided by the API
7. Metadata Harmonization
8. Conclusion
Acknowledgements
Bibliography

1. Introduction
AMS is developing its next generation of it’s Procurement Desktop—Defense product, to be called
Procurement Desktop—Enterprise (PDe). The former is a PowerBuilder, client/server system. The latter
is a Web-based, n-tier, J2EE application. One of the drawbacks to the client/server version of the system
is that there is no central place in which the business rules of the application can be found and invoked
in order to incorporate the functionality of the procurement application into wider business processes.
The business rules are distributed across all the client desktops.

There is a database at the center, but it has only rudimentary business rules in comparison to the rules,
guards and controls found in the rich client. As such, it should not be used as an entry point for other
applications or systems that wish to incorporate procurement data, as the ability to ensure data integrity
is limited, and too great a burden to build in appropriate matching business rules would be placed on
applications wishing to implement such incorporation of procurement data.

An n-tier architecture with a clearly defined business logic layer in an application server provides a
means to allow access to the functionality and information contained in the next generation version of
the application. In addition to the many other benefits of such an architecture—the ability to scale over
a wider range of users and network connections, and to provide a thin-client implementation—this
approach offers a locus for making a public and open API available for use in integrating PDe with other
applications and in making PDe a part of enterprise-wide distributed business processes involving the
numerous applications required to accomplish the complex operations needed for the Department of
Defense to execute its mission.

3 of 10 4/12/2011 2:50 PM
A Web-Services API for a Government Procurement Application file:///C:/home/post-transfer/ws-api-paper.html

The Procurement Desktop Enterprise (PDe) Public API offers a single, comprehensive and open
programmatic interface suitable for integrating PDe with customer systems, other AMS products and
partner products. This document presents an architectural overview of the PDe Public API as a survey to
show the considerations on which we based our decisions and the basic parts of the architecture.

2. Architectural Goals for the Public API

The overall goals of the next generation version of PDe are to move from a tightly coupled, multi-point
integration approach and to meet the market need for integration choice—the power to choose how, and
by whom, integration is accomplished. More specifically, when laying out this architecture, we identified
a number of individual goals. These require that the application be:

XML-based for its payload

Open and standards-based
Scalable to support a distributed application across the enterprise
Directly usable without requiring specific tools
Secure
PKI-enabled
Stable over multiple releases

We hope to show that the architecture described here satisfies these goals as we describe it from various
aspects in this paper.

3. An Integration and API View of the Architecture

From the standpoint of integration with other applications and processes and the Public API presented to
the outside world, the architecture of PDe is one of layers. A graphical depiction of this architecture is
shown in Fig. 1 below.

4 of 10 4/12/2011 2:50 PM
A Web-Services API for a Government Procurement Application file:///C:/home/post-transfer/ws-api-paper.html

Fig. 1: A Layered View of the Integration and API Architecture of PDe

The foundation layer is the business object/rules layer, composed of J2EE business objects. These
objects provide the functionality of the PDe application, and mediate all modifying (create, update,
delete) access to the application database, ensuring that data integrity is maintained. That is, all
manipulation of the database is governed by a single set of processes, so that there can be no
discrepancies in the way data placed in the database is interpreted, as it might be were there to be two
different sets of business rule operations running against the database. Maintenance of the application is
thereby rationalized and simplified.

Next up in the hierarchy of layers is the internal API of the application. Much of this is provided directly
by the business objects. However, there is a need to provide aggregation and service interfaces to other
parts of the application, so some of the internal API is provided as a layer on top of the base business
objects. There is a facility, for instance, for providing introspection into the functionality and information
of the system that is useful in creating EAI adapters for the application.

The Public API layer is a consumer of the private API. It does not directly interact with the database so
that database consistency can be ensured. Architectural consistency required that we not create
components of the application that violated the principle established for having a single business rules
layer that mediates all modifying access to the database. This layer is the focus of this paper, and aspects
of the architecture of the Public API are discussed in rest of this paper. Internally, the Public API is itself
structured into two layers, a base layer and an application layer. The base layer provides common and
reusable technical building blocks that can be used to create API’s for other AMS J2EE applications.
The application layer provides application-specific refinements to the base layer to create a specific
application’s Public API, as with PDe. It is in this layer that the Public API interacts with the PDe
business rules layer.

The next layer up in the integration architecture of PDe is the EAI adapter layer. This layer provides the
necessary software adapters that allow PDe to play in integrations built using EAI tools. In addition to
providing the transformations needed to match specific XML standards or message formats required for
integration into existing business processes, this layer also allows PDe to participate in complex
operations leveraging the message brokering capabilities provided by contemportary EAI tools. AMS
includes webMethods adapters and brokers as a part of its application suite, and can integrate with
others either by coupling EAI integration environments (integrating integrations) or by supporting the
creation of adapters for other EAI tools through the Public API. EAI capabilities are an important
complement to the Public API, which provides the potential for integration, but does not include the
complex machinery needed to couple many disparate applications with mismatched semantics.

The final layer in this architecture is the consuming application. Such applications can connect to the
Public API to accomplish business processes that require tasks to be accomplished by PDe in addition to
their own capabilities, or to provide services to PDe. The use of the Public API can be accomplished by
the use of a variety of tools, and does not require that a consuming application commit to any of the
tools used by AMS in creating the PDe application and its Public API.

4. Web Services Foundation

The architects of the next generation of the product, in looking for an open and standards based

5 of 10 4/12/2011 2:50 PM
A Web-Services API for a Government Procurement Application file:///C:/home/post-transfer/ws-api-paper.html

approach to providing a Public API, had looked to the existing distributed technologies: COM/DCOM,
CORBA and Java. The decision to move to a cross-platform middle tier and build the application using
the Java 2 Enterprise Edition (J2EE) technologies ruled out the use of COM/DCOM and Microsoft-
exclusive technologies. Initially, the architecture group settled on CORBA as the foundation, as this
would provide the openness desired for the API—developers of other applications would not be required
to use Java to talk to PDe but would see the application as just another CORBA API. With the rise and
maturation of Web Services technologies, and the decision to eliminate a rich Swing client, it became
apparent that the earlier distributed technologies like COM/DCOM, CORBA, and Java RMI were not
succeeding in creating the kind of large scale, loosely-coupled distributed applications that we wished to
make PDe a part of.

Web Services, on the other hand, offered the possibility to produce an open API that could participate in
such a distributed architecture. The attraction of using Web Services is the growing support across the
industry, the ties to the World Wide Web and its success as perhaps the largest distributed application
ever, as well as its use in the user interface component of the application, and the simplicity of
developing consuming applications. For instance, we can generate Web Services Description Language
(WSDL) descriptions of the services and content of the Public API, which facilitates tool-driven
development of applications that use the API.

No API of any utility can be used without some sense of the choreography needed to access the API in a
coherent sequence in order to accomplish business tasks. For the present, such choreography is provided
by the documentation for the API, rather than through any of the emerging facilities for registering such
choreographies, such as ebXML or BizTalk. We expect at some point to integrate into such operations,
but we plan on providing such integration at the EAI layer, rather than adding this complexity to the
Public API. Likewise, we are deferring issues of making the Public API discoverable through UDDI and
active XML registries.

5. The REST Architectural Style

An architectural style is an architectural pattern that is applied to the overall organization of a system or
subsystem. At its heart, the REST architectural style is founded on a consistent scheme for naming and
identifying an indefinitely large number of resources and a very limited set of well-known methods for
manipulating and transferring representations of the resources between providers and users of the
resources. It is a data-oriented approach to an API, as opposed to a programming-oriented approach. In
it there are many things and few operations. This is contrasted with the other major technology being
promoted for Web Services, SOAP, which directs an unlimited number of method calls against a single
processing resource or end-point.

In the context of Web Services, the REST style means using the URI name space scheme, and the basic
methods of the HTTP protocol. The URI namespace provides for many resources, and the HTTP
protocol provides a small standardized set of well-known methods.

The REST style using web technologies has other advantages over the SOAP alternative for providing a
Web Services API. The SOAP model follows an RPC model, producing a layered client/server pattern.
In this pattern, consuming applications identify the endpoint to which calls are directed, the methods to
be invoked, and the data involved separately. In the REST style, on the other hand, endpoint and data
are identified together through the resource identification scheme, and methods are constrained to those
provided by HTTP.

6 of 10 4/12/2011 2:50 PM
A Web-Services API for a Government Procurement Application file:///C:/home/post-transfer/ws-api-paper.html

The REST style also produces a more security conscious application. While SOAP also operates over
HTTP, and so is said to be firewall friendly, it is actually using HTTP as a tunnel, and its security
characteristics are essentially opaque to the firewall. Increasingly, using HTTP this way to get through
firewalls is seen to be a misuse, and we see products appearing which act as HTTP firewalls, filtering out
traffic that has such opaque security characteristics. Of course, both SOAP and the REST style can
make use of HTTPS, SSL and so on to make secure connections between API and consumer.

In addition, the Public API, while being open, does not permit just any connection. As with secured
websites, the Public API requires that consuming applications identify themselves and be authenticated
before any interaction can be undertaken. In order to be so authenticated, the consuming application is
required to be registered with the instance of the PDe system with which it intends to interact. When
such registration is accomplished, a security profile for the application is built, and the application’s
access to PDe resources is contolled by Access Control Lists (ACL’s) just as an online interactive user’s
access is so controlled.

Finally, by being entirely based on Web standards and protocols used in the specified fashion rather than
as a tunnel, the REST style supports the HTTP infrastructure—proxies, caches and so forth—without
needing to add anything into the mix or doing anything out of the ordinary for Web operations. This has
positive implications for the scalability of a REST style architecture.

A good basic set of references on the REST architectural style may be found in the Bibliography at the
end of this paper.

6. The XML Provided by the API

The XML resources provided by means of the API are based on existing AMS DTDs for procurement
and contracting related documents. AMS has developed for the Government an EAI adapter to the
current version of the Procurement Desktop—Defense application that provides a set of standard
procurement and contracting documents in XML format to users of the adapter in integrations with other
applications. This XML document set forms the foundation of the XML provided through the Public
API. The document set includes:

incoming PR
bi-directional award
bi-directional conformed modifications
outgoing solicitations
inbound organizations
inbound vendor
outbound Federal Procurement Data System (FPDS)
incoming offeror response
bi-directional contract closeout
bi-directional commitments
bi-directional application advice
outbound milestones

Note that these documents are described with Government terms, and are the primary ones needed to
allow the current application, PD², to participate in wider business processes within the Department of
Defense. For the Public API of the next generation application, these are augmented with some other
resource types expressed in XML. For each document, we also provide an “identifier” view. This is a

7 of 10 4/12/2011 2:50 PM
A Web-Services API for a Government Procurement Application file:///C:/home/post-transfer/ws-api-paper.html

short XML document that provides identifying information about a document, and contains the
information needed to access the full document. There is also a collection version of the identifier view
that provides identifying information about a set of documents. Finally, there is a “count” resource that
provides count information on documents or resources of a given type.

The Public API resource specification allows users to make queries against the above resource types in
order to obtain information about available resources. The Public API and the XML schemata for its
payloads make use of XML standards such as XInclude, XLink, XPath and XPointer. Using these, the
Public API provides ways to request fragments of documents, where such document parts are fully
identified resources with defined URI’s. Documents can also be complex, including references to other
documents and resources.

So far, we have spoken of the XML as though it were delivered bare by the Public API. However,
integration with the PKI enablement components of the PDe architecture will have us packaging
documents, simple and complex, in Secure MIME (S/MIME) envelopes. This has two benefits for our
architecture. First, it provides a standard way of packaging complex documents that include not just the
base XML, but also the related attachments or inclusions found in such documents, most of which are
not XML, but other complex types—Word documents, CAD drawings, images, etc. Second, it provides
the system with a standard way to package cryptographically processed documents, whether XML or
others, by using the S/MIME facilities. The system can sign, encrypt or both sign and encrypt any type
of document and expect that consumers of the Public API or other means of interacting with PDe will be
able to handle these documents without any requirement to be using a specific tool. This capability
provides us with the final elements to give us a complete approach to security in the API.

7. Metadata Harmonization
As noted above, the layered architecture approach to the Public API and the use of EAI adapters for
PDe allows us to provide a rich delivery of XML-based documents directly from the application, as well
as deliver to other applications XML based on one or another standard as needed via transformation in
the EAI layer. This gives us with the freedom to create XML structures for the Public API that can do
all the various things that we need to do, and to express the full range of the capabilities of the
application, while at the same time, maintaining the ability to communicate with industry standard XML
formats.

To make the transformation process from the Public API XML to standard XML dialects, we are
looking to ensure that our XML ultimately becomes based on an industry standard. This is a long term
goal, and needs to be balanced with our goal of keeping the Public API stable while the underlying
application and internal APIs evolve. One way to handle this is to provide additional attributes within
the framework of the existing XML schema we use for our documents. This way, everything that users
of the Public API expect to find in the XML is there, and they can safely ignore the added attributes
—nothing changes for them. At the same time, those who choose to use the additional attributes can do
so, and gain the benefits of the facilities provided by the additional attributes.

For example, AMS is involved with the Metadata Harmonization Project of the Aerospace Industry
Association. This project is building a semantic characterization structure, called the Universal Data
Element Framework (UDEF) for the identification of the specific semantics of data elements defined in
a metadata schema, such as a standard industry-area ontology, a particular database schema, or an XML
schema. The UDEF allows one to analyze the semantics of a given term in a schema, and generate an

8 of 10 4/12/2011 2:50 PM
A Web-Services API for a Government Procurement Application file:///C:/home/post-transfer/ws-api-paper.html

ID, the UDEF ID, that identifies that specific meaning for the term. In this way, one can match terms
semantically across different metadata schemata, an important first step in constructing interoperation
between systems and processes based on these different schemata.

The Public API XML schema will evolve to include an attribute on each element that carries the UDEF
ID. This attribute can be used by any consumer of the API that understands the semantic tagging of data
elements, and ignored safely by all others.

We are also looking at other semantic identification schemes or ontologies which may be incorporated
into the Public API XML, offering consumers of the API more choice to use schemes with which they
may be familiar.

8. Conclusion
We have presented here a quick fly-over of the approach AMS is taking to providing a Public API in its
next generation government procurement application. We believe there is a great deal of power and
flexibility to be found in the REST architectural style and Web Services in creating a web of
interoperating applications providing capabilities such as straight-through processing and hands-off
automated processing to complement the power of the HTML-based Web applications in reaching users.
This approach provides the real possibility of building true large scale, loosely coupled systems across
large enterprises. Finally, the approach we have outlined here provides the beginnings of including
semantic characterization as well—a small first step toward participating in the Semantic Web.

Acknowledgements
Acknowledgement

The authors would like to acknowledge the work and contributions of Brendan Haggerty, Mala Mital,
Robert Schettini, and Mike Stopper from AMS in bringing the design of the PDe Public API to
completion.

Bibliography
[FT01]
“Principled Design of the Modern Web Architecture.” Roy Fielding, Richard Taylor. Proceedings
of the 2000 International Conference on Software Engineering (ICSE 2000), Limerick, Ireland,
June 2000.
[RF01 ]
Architectural Styles and the Design of Network-based Software Architectures. Roy Fielding,
Doctoral Dissertation, University of California, Irvine, 2000.
[PP01 ]
“Second Generation Web Services.” Paul Prescod. xml.com, February, 6, 2002.
http://www.xml.com/pub/a/2002/02/06/rest.html
[PP02 ]
“REST and the Real World.” Paul Prescod. xml.com, February 20, 2002. http://www.xml.com
/pub/a/2002/02/20/rest.html
[KM01 ]

9 of 10 4/12/2011 2:50 PM
A Web-Services API for a Government Procurement Application file:///C:/home/post-transfer/ws-api-paper.html

“NGPD Public API Architecture.” Kevin Mitchell. Unpublished, AMS, Inc. 2002.
[KM02 ]
“NGPD Public API Informal Features List.” Kevin Mitchell. Unpublished, AMS, Inc. 2002.

10 of 10 4/12/2011 2:50 PM