V1.3 FPDS-NG Web Service Integration Specifications

1 Scope
- 1.1 Purpose
2 Conceptual Architecture
3 Service Oriented Architecture
4 FPDS-NG Service Architecture
5 Architectural Goals and Constraints
6 Version Control
7 FPDS-NG Web Services API
- 7.1 Service Object Model
8 Service Definitions and Usage
- 8.1 WSDL Specifications
9 API Standards and Generic Details
- 9.1 Standard Method Signatures
- 9.2 Service Output Parameters
  - 9.2.1 Output Parameter Types
  - 9.2.2 Sample Response Error Messages
10 Specific API Details
11 APPENDIX A Definition and Acronyms
12 Appendix B References
- 12.1 Normative References
- 12.2 Informative References

Scope

Purpose

Under GSA’s initiative and direction, the Federal Procurement Data System (FPDS) Next Generation has been reengineered as a real-time federal enterprise information system. The advent of platform, language, vendor, and tool independent standards has enabled data processing and transport to be carried out seamlessly between heterogeneous systems.

Web services based on SOAP and XML, implemented using Java technologies, are used in FPDS-NG to provide interoperability with various federal procurement systems.

Conceptual Architecture

FPDS-NG Architecture

FPDS-NG consists of two functional domains and one administrative domain. The two functional domains, Data Collection and Business Intelligence/Reporting, are depicted in Figure.

Data Collection: This domain provides multiple mechanisms to feed contract award data from procurement systems throughout the federal government to FPDS-NG. Emphasis is on real-time integration to shorten the lag time between contract award and data availability in FPDS-NG, and to increase data quality by removing batch interfaces and the need to re-key data into agency systems.

Business Intelligence/Reporting: This domain provides multiple mechanisms to report FPDS-NG data to a wide spectrum of interested parties. The reporting mechanisms include canned, ad hoc, and OLAP analysis reporting which are delivered based on the format and schedule preferences established by the user.

System Administration: This domain manages user profiles, user authentication, reference tables, and other system functions such as purging old error records, and monitoring data quality.

Service Oriented Architecture

Software Working Group

The FPDS-NG system architecture, shown in Figure 2–1, is based on a Service-Oriented Architecture (SOA) platform. The choice of a SOA is based on the requirement of GSA to produce a web service based application that will allow integration of FPDS-NG with agency systems. All identifiable system functions are published as services that external systems invoke using open standards over a network. This architecture exposes all system functions including business logic, GUI screens, and reports making them all accessible to agency systems. The value of a SOA-based approach is realized in the reusability of the components. Reusability offers the government tremendous savings of time and money as software development is leveraged by many systems without the need for additional development or redundant efforts. Reusability also provides the government with the ability to construct authoritative services for vital information (e.g. NAICS codes, vendor data, etc). SOA is the architectural structure underpinning web services and is developed to the J2EE standard. The technologies used to invoke web services promote interoperability. These technologies include:

XML, which defines a universal way of representing data
SOAP, which provides the transport mechanism for web services
WSDL, which describes a web service definition
UDDI which allows users and applications to locate or publish web services in a registry.

FPDS-NG Service Architecture

Figure 4–1 describes the FPDS-NG high level service architecture. It uses a building-block approach to maximize reusability. The FPDS-NG service architecture contains several layers, each of which is fully reusable. For example, the business services are used by migration software, GUI services, and external procurement systems. The layers are:

COTS Layer: This layer consists of the Oracle 10g database and the Informatica™ reporting server. The Informatica™ reporting server utilizes the Oracle 10g database for all data queries.
FPDS-NG Services: This layer consists of the GUI and business services which centralize all FPDS-NG business logic. The GUI services layer represents all FPDS-NG screens. The GUI screens use the business services to validate and post FPDS-NG transactions.
FPDS-NG Applications: This layer represents FPDS-NG software that employs reusable services. For example, the batch processor and migration software use the business services (Note: batch submission is no longer supported in Version 1.3)
External Systems: This layer represents legacy systems and COTS products that wish to integrate with FPDS-NG services. FPDS-NG allows integrators use any of the business, GUI service or reporting services. For example, agencies may integrate with FPDS-NG at the business services level or reuse the FPDS-NG data collection screens.

Document Overview

This document introduces the web services system architecture that exposes one point of entry to FPDS-NG. The web services APIs will act as the gateway to access all functionality on the server side. The following set of modules that belong to FPDS-NG use the web services APIs to achieve their functionality.

GUI services that allow creation or modification of awards, IDVs, reference and system administration data.
Business services that allow the integrators to launch the FPDS-NG data collection screens from within the COTS/GOTS products
Reporting services that allow the integrators to launch FPDS-NG reports from within the COTS/GOTS product

New Version updates for 1.2

With the release of Version 1.2 of the Business and GUI web services, it was necessary to make certain changes to the web services system architecture. These changes are listed in the table below, and included in the appropriate section throughout the document. The changes listed in this table are linked to the section in the document that addresses each particular change.

New Version updates for 1.3

Version 1.3 of the Business Services includes the following additional functionality:

Transfer of Awards/IDVs
Ability to change the PIID of final Awards/IDVs.

The changes listed in Table 4 2 include a link to the section in the document that addresses each change.

Architectural Goals and Constraints

Each Web Service API will follow the set of guidelines described below that are essential to any published set of APIs accessible from anywhere via the Internet.

Simplicity: An API addresses a simple business process and is atomic.
Interoperability: An API is platform independent. Web services have been the solution of choice throughout the industry to address heterogeneous distributed systems. The FPDS-NG web services are designed to be platform independent in order to achieve maximum interoperability.
Nomenclature Consistency: An API follows a specific set of naming conventions that are used consistently.
Functional Consistency: An API behaves the same at all times for the same set of data inputs unless there are processing business logic and rules that are driven by factors like time, data history, etc.
Macro Level API: An API translates a business use case into one service that completes the business process in one transaction.
Flexibility: An APIs is versioned, allowing clients to migrate to the next version when they are ready.
Appropriate Payload Size: List Retrieval API services limit the number of values returned, so that the payload is not exceeded beyond the limit the middle-tier can handle.
Stateless: An API service is stateless.
Secure: All API input contains the user and source data used for authentication.
Error Processing: The API returns a comprehensive and complete set of error codes and corresponding messages.
Error Batching: An API service encapsulates all errors during the service execution into a single response. This allows the service customer to send back the corrected request without running an iterative error correction process for each attribute or entity of the request.

Version Control

Web Service API Versioning

Business requirements that change an API will be appropriately collated and prioritized with the consent of GSA and new web services or new versions of existing web services will be engineered and deployed. Client systems can continue using the older version of the API until they are ready to migrate to the newer version. The next sections describe version control of the Web Service API.

Implementation

The processing and business logic of the web services are artifacts of the web service that are prone to change, driven by business process modifications and enhancements. When the Web Service API remains the same, but the business process carried out by the service changes, a new version is announced and released without affecting the current version.

Service Input

Changes to the input parameters of any particular web service are released as a new version.

Service Output

When the output parameters passed back to the caller as a web service response change, the changes will take effect in a separate, new version of the web service.

Service Errors

The errors section of the web service output is subject to change due to changes in the following:

Input parameters
Output parameters
Business processes and rules underlying the web services
Technical implementation changes to the web services.

The error changes will be made effective in the newer version of the Web Service API.

Schema Changes

The schema definitions for the domain input parameter(s) are modified to support changed or additional data. The method signature remains the same but a newer version of the Web Service API is published to process the new/deleted data in the schema.

Concurrent Version Support

Concurrent versions of the API will be supported to allow the clients to connect to the previous web services versions. At any given point of time, there may be two or more concurrent versions supported. The older version of the API will be provided to give clients time to adapt to the changes required by the new version.

API Versioning conventions

Newer versions of the API will be hosted under the URL, which can be located using the FPDS-NG directory tree suffixed with the version number. For example:

The namespaces referenced by the API follow the same naming convention. For example:

Newer versions of the WSDL will be published through the UDDI registry, which provides the list of versions currently supported.

FPDS-NG Web Services API

Service Object Model

The service object model depicts the data entities at the domain level as well as the lower level objects that are reused between the different modules or services of the system. Figure 7–1 shows the service layer that caters to the operations on the objects. The operations include creating, retrieving, updating, validating, and other business layer activities that serve users through GUI services, batch processes, and reporting applications.

Service Definitions and Usage

WSDL Specifications

The following abstract from the W3C March 2001 note 15 describes the WSDL: WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. Related concrete endpoints are combined into abstract endpoints (services). WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate.

The bindings described in this document specifically deal with the use of WSDL in conjunction with SOAP 1.1, HTTP GET/POST, and MIME.

Table 7 1 shows the FPDS-NG Web nomenclature. Section 1.4.2 Definitions contains definitions of the WSDL Parameters explained below.

All complex types specified by the FPDS-NG Web Services include the targetNamespace in the corresponding WSDL and are named after the complex type or the domain level object, i.e., Award.xsd, Country.xsd, etc.

The schemas are located and loadable from a public URL using the http protocol. Availability of the web services over other protocols such as ftp and SMTP is not supported due to security risks.

API Standards and Generic Details

The web services APIs of the FPDS-NG domain objects encompass the following standards:

Service calls in FPDS-NG are authenticated by checking for valid User ID/Password.
Service calls are checked for authorization before serving the request. For example, the create service on Award will check if the user has the privilege to create an Award in FPDS-NG.
Web Services APIs supported for domain entities such as Award and IDV. This includes common business services such as create, get, update and delete.
Service calls use a standard method signature. All the business classes in the FPDS-NG system have the same method signature. Standardization involves the same set of input and output parameters and their generic structures for the web services.
Service calls contain a logging and error mechanism. All the requests are logged in the underlying generic layer of the business classes.

Standard Method Signatures

All the methods use the following signatures:

All the input and output parameters are in XML Format.
The inputs to the service methods and the subsequent domain classes are encapsulated in the authentication key and the input parameters.

Service Output Parameters

The service output parameters are represented in Meta XML strings. Table 8 3 describes the XML meta-response.

Output Parameter Types

All unauthorized transaction operations are returned with Authentication Errors. Error messages are returned when the operation fails. Only a sample list of errors is provided for each operation Please refer to the FPDS-NG Error Listings for a complete list of errors. The output parameter types are described in Table 8 4.

Sample Response Error Messages

<response>
  <listOfErrors>
    <error>
      <elementName>searchCriteriaXML</elementName>
      <errorCode>10141</errorCode>
      <errorMessage>Service Unavailable Please try again later</errorMessage>
    </error>
    <error>
      <elementName>PIID</elementName>
      <errorCode>10200</errorCode>
      <errorMessage>Cannot create award. PIID already exists in the database</errorMessage>
    </error>
  </listOfErrors>
  <listOfWarnings>
    <warning>
      <elementName>BundledRequirement</elementName>
      <warningCode>30501</warningCode>
      <warningMessage> BundledRequirement is not required for Award type BPA call. Ignoring the value </warningMessage>
    </warning>
  </listOfWarnings>
</response>

Specific API Details

APPENDIX A Definition and Acronyms

All standard and non-standard terms and abbreviations used in this specifications document are explained in the following table.

**Acronyms**
Acronym	Definition
API	Application Programming Interface
CRU	Create, Read, Update
CRUD	Create, Read, Update, Delete
EJB	Enterprise Java Beans
FPDS-NG	Federal Procurement Data System
FTP	File Transfer Protocol
GUI	Graphical User Interface
HTTP	HyperText Transfer Protocol
HTTPS	Secure HyperText Transfer Protocol
MIME	Multipurpose Internet Mail Extensions
NAICS	North American Industry Classification System codes
OLAP	On-Line Analytical Processing
PSC	Product Service Codes
RPC or rpc	Remote Process Call
SOAP	Simple Object Access Protocol
URL	Uniform Resource Locator
WSDL	Web Services Definition Language
XML	eXtensible Markup Language
XSD	XML Schema Definition
XSL	eXtensible Stylesheet Language

Definitions

The following list contains definitions of the terms used in this document:

Port Type – A Port type is an abstract set of operations supported by one or more web service providers (i.e., all of the web services available for an award).
Binding – A concrete protocol and data format specification for a particular port type.
Types – A container for data type definitions using some type system (such as XSD).
Service – A collection of related endpoints
Target Name Space. The target namespace serves to identify the namespace within which the association between the component and its name exists

Appendix B References

Normative References

[RFC 2119] IETF "RFC 2119: Keywords for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)

[RFC 2396] IETF "RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998. (See http://www.ietf.org/rfc/rfc2396.txt.)

[RFC 2616] IETF "RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1", R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk Nielsen, T. Berners-Lee, January 1997. (See http://www.ietf.org/rfc/rfc2616.txt.)

[XML Schema Part 1] W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.)

[XML Schema Part 2] W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.)

[SOAP Part 0] W3C Proposed Recommendation "SOAP Version 1.2 Part 0: Primer", Nilo Mitra, (see http://www.w3.org/TR/soap12-part1.)

Informative References

[Data Element Dictionary] GSA FPDS-NGNG Data Element Dictionary #GS00M02PDR0008

[FPDS-NG-RFP] Request for Proposal (RFP) #GS00M02PDR0008

[FPDS-NGGCE Proposal Volume I] GCE Technical Proposal - Option 1, submitted to GSA.

[WSDL 1.1] Web Services Description Language (WSDL) 1.1 W3C Note 15 March 2001 (See http://www.w3.org/TR/2001/NOTE-wsdl-20010315 ).