Generic Web Services Guidelines
- R. Andres Ferreyra (Unlicensed)
- Charlie Nuzzolo (Unlicensed)
- Jim Wilson
Modified on 2011-02-08 16:40 by Administrator
1. Introduction
This document provides guidelines for producing and consuming web services among companies in the agriculture industry. It includes a sample Web Services Description Language (WSDL) document that is designed to support business document exchange (in contrast to fine-grained operation invocations.)
2. Key Words Used to Indicate Requirement Levels
Key words used to indicate requirements levels are defined at http://www.ietf.org/rfc/rfc2119.txt.
Per the reference:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
2.1 Transport and Security Protocols
HTTPS MUST be used for all Web service interactions. The Web Services Security: UsernameToken Profile 1.1 OASIS Standard Specification, 1 February 2006 must be used for identity and authentication. It may be found at http://www.oasis-open.org/committees/download.php/16782/wss-v1.1-spec-os-UsernameTokenProfile.pdf.
The WS-I Basic Security Profile 1.1 provides examples that may be useful to implementers. It is available at http://www.ws-i.org/Profiles/BasicSecurityProfile-1.1.html.
The following WSDL will serve as the basis for discussion throughout the remainder of this document.
2.2 Sample WSDL with Parameters
2.3 Definitions
For the purposes of discussion in this specification, the following terms are defined:
AUBTP: is an acronym for agreed upon by trading partners. This refers to two or more trading partners agreeing to a more specific use of some aspect of an eBusiness standard or guideline—an aspect that, by definition, would be more generically defined.
client: a trading partner invoking a web service
metadata elements: refers to all child elements of the inboundData and outboundData elements other than the xmlPayload element, which includes the following elements: businessProcess, processStep, partnerId, partnerType, conversationId, and messageId.
protocol: the supported values, semantics, and usage patterns of the metadata elements AUBTP
request: an HTTPS request
response: an HTTPS response to a request or where a ppropriate a TechnicalAck.
service provider: a trading partner providing web services
TechnicalAck: a message sent back to the client to acknowledge the receipt of a request.
2.4 Specification for AgGateway Services
The AgGateway WSDL metadata elements are intended to support a messaging architecture where the routing/transport responsibilities may be separated from the business processing responsibilities. This enables a message to be routed without inspecting the payload.
The supported values, semantics, and usage patterns for metadata elements are ultimately determined by trading-partner pairs engaged in eBusiness. Trading-partner pairs will often agree to use values, semantics, and usage patterns established by a group representing an industry sector (e.g., seed, feed, ornamental horticulture.)
2.5 Usage Definition of “inboundData” Elements (i.e., Request)
2.5.1 businessProcess
businessProcess identifies the business process associated with the xmlPayload element content. Multiple messages may be required to complete a particular businessProcess, in which case the processStep may be used to specify the message type. However, a processStep MAY not be defined when the business process definition contains only one process step, AUBTP. The businessProcess values defined by AgGateway MUST be defined such that there is a one-to-one identifier-to-process definition correspondence.
2.5.2 processStep
processStep identifies the business process step associated xmlPayload element content. If a processStep element is present then a businessProcess element must be present as well.
The function of some web services is simply for a client to post a message to a service provider with only success/failure indication in a response. In such situations it is RECOMMENDED that the processStep value in the response be either be a TechnicalAck or some equivalent.
2.5.3 partnerId
partnerId identifies the partner sending the request. If a partnerId element is present then a partnerType element MUST be present as well.
It is RECOMMENDED that this identify the physical sender. If a business partner were using a service bureau to send messages, for example, the partnerId would identify the service bureau rather than the business partner. For business partners handling their own communications, of course, the physical sender and the business partner would be one and the same.
2.5.4 PartnerType
partnerType indicates the partnerId identifier. The value MUST be taken from the Ag eStandards cidxListPartnerAgencyAttribute type definition.
2.5.5 conversationId
conversationId identifies an instance of a business process definition between two trading partners, which enables the trading partners to relate two or more messages to the same process instance.
Global uniqueness is NOT REQUIRED. Uniqueness requirements will be AUBTP.
2.5.6 messageId
messageId identifies a message. It must be globally unique from a business perspective. In other words, every message queued for delivery from a business perspective must have a unique identifier. Transport services may need to send a message more than one time to ensure delivery. With each attempt to send the same message, the messageId MUST remain the same.
2.6 Usage Definition of "outboundData" Elements (i.e., Response)
2.6.1 processStep
See discussion of processStep in the inboundData Elements section above.
2.6.2 messageId
See discussion of processStep in the inboundData Elements section above.
2.7 Partner Identification Issues
For any given message there are potentially at least three ways a partner may be identified:
- WS-Security Username/Password
- partnerId/partnerType element values
- information expressed in the xmlPayload element content
When information may be expressed in two or more places in a message, the possibility exists that the identifiers fail to resolve to the same expected partner. Testing for such issues is NOT REQUIRED (by this specification). Furthermore, if such issues are identified, this specification does not specify how they MUST or even SHOULD be addressed.
2.7.1 Service Provider Message Processing Issues
A service provider MUST return a SOAP fault response under the following conditions:
- The client message does not conform to the schema specified in the WSDL
- The client message does not contain an inboundData element
- WS-Security is required and the client fails authentication
- WS-Security is required and the client fails authorization
A service provider MAY return a SOAP fault response under the following conditions:
- Missing business data
- Invalid business data
- WS-Security is used, the
- Internal issues at the service provider
- Other reasons request processing failed
It is RECOMMENDED that the SOAP fault responses contain an explanation of the fault. A service provider is NOT REQUIRED to log SOAP fault responses. In some cases this may mean that the client must maintain artifacts sufficient to investigate issues.
SOAP fault responses must not contain a messageId, a processStep, or an outboundData element.
3.0 Sample Request XML – Generic Request XML Message
A more fitting section title is suggested. Is this Errata and context?
Work on the GenericDocumentRequest will continue, including refinement of the schema and specification of how the parameters should be used, so that it can be used with future services. This work, including the full GenericDocumentRequest schema, will be included in future versions of this document.
Some specifications and notes so far on this Generic Request document: Are these specifications or are they business rules implied by the document?
- If parameters StartDate/EndDate and DocumentReference are not sent, then the consumer would receive all documents that are queued up for that specific consumer.
- If parameters StartDate/EndDate OR DocumentReference are sent, then the returned list is based on the parameters whether or not the documents have been sent.
Here are some of the questions regarding the use of the GenericDocumentRequest parameters which have been identified so far:
- What combination of parameters means to send all documents (e.g. ShipNotices or Invoices) not previously sent?
- When StartDate/EndDate are set, does it mean to send all documents between those dates which were not previously sent, or does it mean to resend already-sent documents only, or does it mean send all whether previously sent or not?
- If MaximumDocuments is specified, what is the ordering criteria if any (oldest first, newest first, something else)?
- If DocumentReference is set, does the client wants that document whether it has previously received it or not? Note the particular data element in the desired document which the DocumentReference value is supposed to match must be specified for each service, e.g. for ShipNotice it should match CIDX element xxx/yyy/zzz/etc (full XPath to CIDX element). Also, is it supposed to be an exact match, or a “starts with” match?
- When documents are sent due to StateDate/EndDate or DocumentReference being set, does this mean they are then considered already sent for purposes of the client later requesting all unsent documents?
Another area to be reviewed is the desired response when GenericDocumentRequest is used. Assuming multiple documents can be returned, should they be returned in multiple xmlPayload elements (one document per xmlPayload element), or should we define collection elements analogous to the CIDX ShipNoticeList and InvoiceList and send that in a single xmlPayload element, or can this vary depending on the specific service?
3.1 Parameters in the Generic Document Request
| Parameter Name | Element Description | Required |
|---|---|---|
| DocumentType | Element should contain the value of the root tag/document being requested. | Yes |
| DateRange – StartDate, EndDate | DateRange – StartDate, EndDate | No |
| MaximumDocuments | Maximum number of documents the consumer wants to receive back. | Yes |
| DocumentReference | Specific document ID on transaction being requested. If sent, then takes precedence over StartDate and EndDate. | No |