This chapter identifies the set of design guidelines that should affect information system design choices for implementing Web Services. These guidelines address only the architectural aspects of systems, independent of any individual system’s business requirements. This topic establishes descriptive attributes for the architectural support of Web Services implementations to assure common characterization of what constitutes a Web Service.
Web Services Versioning
By design, the implementation of services can change with little impact to the service consumers (downtime, rework, compatibility, etc.). Changing the interfaces—the way one invokes those services—requires changes to the service consumers as well. CMS recommends that architects and designers focus on the impact of each change to service interfaces. Changing an interface cannot be done unilaterally. Instead, adherence to a governance process will facilitate negotiation to resolve differences between Web Service providers and consumers.
Web Services versioning provides a mechanism to allow service consumers to continue using previous versions of a web service while working on their transition plans.
Version Implementation
CMS employs the following principal methods of versioning Web Services:
- Endpoint (URL) versioning
- Message versioning (either using JSON or XML versioning)
- XSD versioning
In URL versioning, the major version number of a web service endpoint is appended to the URL. In Message versioning, the message header contains a version number field. This can be a version in the XML or JSON payload or it can be a XML XSD version. In XSD versioning, the XSD for the WSDL contains the version as part of the schema definition.
URL versioning is generally the simplest to explain and use.
Versioning Scheme
The SemVer 2.0.0 (Semantic Versioning) specification provides a mechanism for naming versions of products following de facto industry standards. The scheme is summarized as follows:
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
For REST services, the version is reflected in the URI or as a field in the payload. XML payloads may use XML XSD versioning. Most often, the URI would reflect the version.
For SOAP services, the URI or WSDL reflect the version.
Dependencies on Standards
SOAP Web Service Standards
Successfully implementing solutions using this chapter depends on having integrators address multiple standards, appropriate elements, and other CMS TRA chapters.
The extensible nature of Web Services’ architecture has led to exponential growth in Web Services standards and specifications as standards bodies and companies attempt to leverage this technology. New specifications allow new functionality for Web Services, and these specifications are subsequently submitted to standardization bodies, such as the W3C or OASIS. Standardization is necessary to ensure that different implementations of Web Services engines engage one another seamlessly and thus fulfill the interoperability objective of Web Services.
Although this recent activity has created numerous standards and specifications that address many aspects of Web Services, only a narrow set are relevant to this supplement, as shown in SOAP-Specific Web Concepts and Definitions. For a more detailed discussion, please refer to the following sources:
- World Wide Web Consortium
- OASIS Web Services Interoperability (WS-I) (now part of Oasis Open)
- OASIS Service Reference Model (SRM) Technical Committee
|
Category |
Standards |
Notes |
|---|---|---|
|
Security |
|
Focus on Security Assertion Markup Language (SAML) and the related federated security model: |
|
Processes |
|
Focus on support of distributed processes, where the participant initiating the process maintains a controlling position throughout the lifetime of the process. Future support should improve monitoring a process’s progress based on rules. |
|
Data Formats |
|
SOAP payloads are XML documents. |
REST Web Service Standards
For REST, the standards are different and there are fewer of them. REST relies on the infrastructure of the World Wide Web and the HTTP protocol for standards. REST relies on media types to identify payload (data) standards. Each Internet Assigned Numbers Authority (IANA) registered media type has a template that defines its use and format. REST Web Service Standards presents the REST Web Service Standards for Security, Transactions, and Data Format.