7 Web Service Standards and Conventions

This chapter includes standards and conventions for Web service naming and versioning.

Web Service Naming

The following standards and conventions apply to the naming of Web services.

The Web service name should be a business noun, concept or process.

Item	Description
Recommendation	The Web service name should be a business noun, a business concept, or a business process.
Rationale	To be in alignment with other Web service standards.
Example	Supplier Service

Avoid verbs when naming Web services.

Item	Description
Recommendation	The Web service name should be a business noun, a business concept, or a business process.
Rationale	Verbs generally are at the operation level, not at the service level.
Example	Avoid names such as CreateSupplierService.

The first 30 characters of the Web service name must be unique.

Item	Description
Recommendation	The first 30 characters of the Web service name must be unique.
Rationale	Some systems truncate names at 30 characters.
Example	N/A

The integration/services qualifier should be in the namespace.

Item	Description
Recommendation	The integration/services qualifier should be in the namespace.
Rationale
Example	http://www.oracle.com/retail/rms/integration/services/PayTermService.

The Web service namespace should contain the application short name.

Item	Description
Recommendation	The Web service namespace should contain the application short name.
Rationale	Multiple applications may publish services with similar names. To categorize and identify which application is hosting what service, the service namespace should contain the application short name.
Example	http://www.oracle.com/retail/rms/integration/services/PayTermService.

The Web service type should be document/literal wrapped.

Item	Description
Recommendation	The Web service type should be document/literal wrapped.
Rationale	This is defined in the WSDL.
Example	<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/> <operation name="createPayTermBO"> <ns21:PolicyReference xmlns:ns21="http://www.w3.org/ns/ws-policy" URI="#PayTermServicePortBinding_createPayTermBO_WSAT_Policy"/> <soap:operation soapAction=""/> <input> <soap:body use="literal"/> </input>

The Web service must comply with Web Service Basic Profile 1.1.

Item	Description
Recommendation	The Web service must comply with Web Service Basic Profile 1.1.
Rationale	The specification is called the WS-I Basic Profile 1.1. It consists of a set of non-proprietary Web services specifications, clarifications, refinements, interpretations, and amplifications of those specifications which promote interoperability.
Example	N/A

The Web service operation naming pattern should be verb<TopLevelComplexType>(TopLevelComplexType variable).

Item	Description
Recommendation	The operation name pattern should be either of the following: verb<TopLevelComplexType>( TopLevelComplexType variable) verb<NonTopLevelComplexType>Using<TopLevelComplexType>( TopLevelComplexType variable). Non top level Complex Type cannot be empty, that is in xml we cannot have something like <ExtOfReportLocDesc></ExtOfReportLocDesc> or <ExtOfReportLocDesc/>.
Rationale	The operation name should reflect the Top Level Complex Type of the service's primary entity object to ensure the name is unambiguous.
Example	createItemListBO

Web Service Versioning

Service versioning is in the namespace, including the application and the version identifier.

The service namespace is versioned.

Item	Description
Recommendation	The WSDL for the RBS will have the namespace versioned.
Rationale	For breaking changes only, the WSDL for the RBS will have the namespace versioned. http://www.oracle.com/retail/<retail app>/integration/services/<service name>/V<incremental change number>
Example	http://www.oracle.com/retail/rms/integration/services/PayTermService/V2