Upgrading To Applicant Web Service Library V2.0

The latest version of the Grants.gov Applicant Web Service Library is Version 2.0 (V2.0). It consists of the following major enhancements:

  • Support for large submissions (up to 1.2 Gigabytes). Both single project and multi-project submissions now can be streamed to Grants.gov, greatly reducing size restrictions.
  • Enhanced validation using strongly typed objects in the WSDL. It is easier for users to validate their XML prior to invoking the web service.
  • New schemas were added to store common data elements to increase consistency in naming conventions.

NOTE: S2S V0 and V1 endpoints were discontinued January 4, 2016. Please use or upgrade to the S2S V2.0 endpoint.

Resources for Upgrading to Version 2.0

For applicants that are upgrading to Applicant Web Services Version 2.0:

About Web Service V2.0

Validation

All V2.0 web services were changed to use strongly typed objects to allow the interfaces to become more descriptive in their input and output parameters. Clients are no longer passing an XML string; rather the client is populating the values in a value object and then dispatching it to the server in the input message. This change allows Grants.gov to perform an initial validation on the structure and the contents of each parameter upon invocation of the web service.

Using strongly typed objects and validation upon invocation requires optional parameters are set to null instead of an empty string. Empty tags can no longer be included in the XML for null fields. This validation checks the structure and the contents of each parameter. For example, CFDANumber is an optional field in the GetOpportunities web service and must be set to null to exclude this field from the web service call.

MTOM

V2.0 upgraded to the Message Transmission Optimization Mechanism (MTOM) in the application server for attachment streaming to support large submissions. This required a change in the signatures for the web services for receiving and sending attachments.

On the client side, the enabling of the MTOM feature is through setting properties when acquiring the service port. The code snippet below shows how the client can enable the MTOM feature:

ApplicantWebServicesPortType port = service.getApplicantWebServicesSoapPort( new MTOMFeature(true) );
               BindingProvider bp = ( BindingProvider ) port;
          bp.getRequestContext().put( JAXWSProperties.HTTP_CLIENT_STREAMING_CHUNK_SIZE, 8192 );

External Schemas

In V2.0, the WSDL references external schemas act as a central repository for the different object types and elements used in each WSDL. This technique enables consistency of the various data structures used throughout the web service interfaces. The following are the active schemas for the Applicant web services:

The following common schema was added to standardize the naming convention:

To use this common schema, set the GrantsCommonElements-V1.0 namespace declaration to 'xmlns:GrantsCommonElements'. The following common schema was added to standardize the definition of the common elements: