This chapter employs commonly used CMS and Internet terminology, as described below.
SOAP
SOAP is an XML-based, open standards protocol for integrating applications and sending messages. SOAP Web Services use the XML data language for expressing three different concepts: service description, data, and metadata. Each concept has a distinct XML-based language as follows:
-
Web Services Description Language describes a SOAP Web Service. The WSDL describes two parts—the messages (requests and replies) as well as service communication information.
-
SOAP is the on-the-wire XML stream for a message. It contains an envelope with a header and body. The header includes addressing and security that describe how to process the body. The body consists of the bulk of the message.
-
XML Schema Description (XSD) is the definition language to describe the structure of the XML schemas used as well as the legal values for each element. Complex schemas may employ an additional language called Schematron to express cross-schema validation (see also ISO/IEC 19757-3:2020 Information technology – Document Schema Definition Language (DSDL) – Part 3: Rule-based validation using Schematron). The table SOAP-Specific Web Concepts and Definitions presents the applicable SOAP-specific Web concepts and definitions used in this chapter.
SOAP messages are transport independent. Applications transmit SOAP-formatted messages using web standard protocols such as HTTP and Advanced Message Queuing Protocol (AMQP) as well as proprietary protocols such as IBM MQ Series or Microsoft Message Queuing (MSMQ). The Web Services standards allow SOAP messages to contain text or binary attachments.
REST
REST is an architectural pattern based on the underpinnings of the World Wide Web. REST works with a variety of web protocols, data formats, Multipurpose Internet Mail Extension (MIME) types, operations, message sequences, and resources. Resources include web pages visible to users and data objects consumed by software applications. REST uses HTTP or HTTPS to identify and act on information resources. It constrains the interface to a set of well-known, standard operations (e.g., GET, POST, PUT, and DELETE). REST’s aim is to exchange content with resources that maintain the state of information. REST uses URIs to identify resources and HTTP operations to act on those resources. SOAP relies principally on XML, while REST relies on HTTP and JSON.
Ultimately, REST proposes to leverage the current operations of the Web rather than adapting the Web to a new way of working. REST-Specific Web Concepts and Definitions presents the applicable REST-specific Web concepts and definitions used in this chapter.
|
Web Concept |
Definition |
|---|---|
|
Resources |
An informational resource is any piece of data or content that a URI can uniquely identify and that the Web can express in a textual or binary representation and transmit across a network. |
|
Uniform Resource Identifier |
A URI identifies a REST resource. Unlike SOAP Web Services that typically use a single URI endpoint, REST uses as many URIs as necessary to describe each of the resources used. |
|
Data Representations |
A REST request message specifies the representation, or Multipurpose Internet Extension (MIME) type 5 (“application/” per RFC 2046), of the response message. REST specifies the response MIME type by:
The response also contains a MIME type to designate the information type. |
|
Operations |
REST uses the operations defined in the HTTP protocol (RFC 2616), namely GET, PUT, POST, DELETE, HEAD, OPTIONS, TRACE, and CONNECT, but it is not limited to those operations. Extensions should be carefully considered because this may limit reuse and hamper compatibility. |
|
Statelessness |
REST uses HTTP request and response messages. The resources hold their own state, and the REST requests cause changes in the state of those resources. The requestor (whether client or another service) holds the state of the conversation; this explains the large scalability of REST. HTTP cookies are often used to maintain session state. |
|
Hypermedia |
Hypermedia is the fundamental organizing structure of the Web. Hypermedia can have a role in Web Services design and can enable both dynamic discovery and state management. There is a form of REST called “Hypermedia As The Engine Of Application State” (HATEOAS). |
REST supports various other patterns:
-
Asynchronous JavaScript and XML (AJAX) calls. AJAX allows a web page to invoke a REST web service directly from the browser. This allows for responsive webpages as well as Single Page Applications (SPA).
-
Really Simple Syndication feeds. RSS is an XML-based polling publish-subscribe method that allows a user to subscribe to a file and get an update when the file changes. Blogs and other online publications use RSS extensively.
-
Atom feeds. Atom feeds (RFC 4287) are another XML-based publish-subscribe method similar to RSS, accessed via the Atom Publishing Protocol (AtomPub).
The REST pattern may use alternate operations (other than HTTP GET, PUT, POST, or DELETE) and alternate MIME types other than XML and JSON, although this is uncommon. REST messages can transmit textual or binary attachments via hypertext or by sending a binary file as the REST message body.
SOA and Web Service Roles
There are three principal roles in a SOA—service providers, service consumers, and intermediaries:
-
Service Provider. An organization that creates, deploys, maintains, and operates a service for use by others. The provider is responsible for implementing and operating the web service as a sustainable capability over its lifetime of use.
-
Service Consumer. An organization that consumes (i.e., invokes, executes, or calls) web services. A web service consumer could be another web service, a business application, or a system component that is not a service.
-
Service Intermediary. An organization that acts as both a service consumer and provider.
Service Interfaces
As defined by the OASIS Reference Architecture Foundation for Service Oriented Architecture (SOA) and the DOJ Global Reference Architecture (GRA), the service interface is “the means for interacting with a service. It includes the specific protocols, commands, and information exchange by which actions are initiated [on the service].” Best practice calls for describing a service interface in an open standard, machine-interpretable format (i.e., a format whose contents are capable of automated processing by a computer), such as WSDL.
The service interface is the technical specification for the data exchanges (inputs, outputs, and error conditions), including specific description of data types, formats, constraints, assumptions, and expectations. The software code for an interface typically only describes the data exchanges but not the assumptions and expectations. It is important to document these as well because they may not appear expressed in the software. For example, a service that appends data to a database may expect rejection of any duplicates; however, there is no way to express this in the machine-readable software interface. It is important to document such assumptions in the human-readable text. The CMS Interface Control Document records this interface.
The core of a service contract will comprise the service description that expresses its technical interface as well as the assumptions, preconditions, and post-conditions that define its service contract. In addition to normal operation, it must define how service consumers will recognize service failure. For example, for SOAP Services, it would define the SOAP Faults as well as use of HTTP status codes (if appropriate).
In practice, a service interface is, in effect, an agreement (a service contract) between consumers and providers committing each to a course of action. The service contract is not a legal document but rather a technical specification that defines what the service will and will not do. The service contract gives service consumers a clear understanding of each service’s definition, limitations, and constraints.
Message Structure
Regardless of implementation, the basic structure of a web service is message oriented and involves an envelope, a header, and a body. Optionally, there may be attachments.
The envelope represents the message as a whole. In the physical world, there is data on the outside of the envelope and data on the inside. In the web services world, the data on the outside (which refers to source and destination address) is called the header. The data on the inside is the body or content.
The header provides routing information, timestamps, and other data about the message. The body is either the request or the response data.
The body can often be encrypted or digitally signed independently from the header. The header identifies whether to encrypt the body (or a portion of the body).
The HTTP headers, depending on SOAP version, play less of a role in SOAP Web Service execution than in REST services. REST Web Services use the HTTP header extensively and place the message body in the content portion of the HTTP request or response.
Transport
In a Web Services architecture, the transport functions as the network layer that conveys Web Service messages between service providers and consumers. HTTP (and HTTP/S) are the most commonly used transport layers for Web Services. CMS makes no transport or protocol restrictions other than adherence to CMS security standards. As a result, it is possible to use alternative protocols such as AMQP (ISO/IEC 19464), proprietary protocols such as IBM WebSphere MQ, or even Internet Inter-ORB Protocol (IIOP) to convey web services. CMS recommends using standard, openly available protocols (like HTTP and AMQP) for greater interoperability without cost to either consumer or provider whenever possible.
Service Repository
A service repository is a platform-independent directory that catalogs all services, providing an authoritative source for service descriptions, classification, and categorization information. It may contain such information as service level agreements, version descriptions, capacity, integrity, and security constraints. The repository organizes the services for easy discovery.
Repositories support both web service providers and consumers by providing an authoritative source for service information. Publishers post and manage configuration of metadata artifacts to support information sharing and to ensure their reuse across the boundaries of participating stakeholders. Consumers can search for services and retrieve essential information to use Web Services. The service repository should play an important role in governance and configuration management for Web Services. Some repositories support workflow, allowing submission of Web Services for approval and eventual publication through a documented process. This supports the governance process by offering service management automation.
Enterprise Service Bus
The Enterprise Service Bus (ESB) is an integration infrastructure for implementing independent sharing of data and business processes among connected Web Services.
ESB-connected consumers interact with various service providers to complete business processes. The ESB routes SOAP requests to multiple service providers. Components Connected with an ESB depicts Web Services and other components as they connect via an ESB.
Enterprise Messaging
Enterprise message (not e-mail) is a mechanism for sending and receiving messages, including but not limited to XML-based messages, either with request-reply or publish and subscribe (“pub-sub”) semantics between applications. In addition, enterprise messaging provides delivery options such as message queuing, fire and forget, and guaranteed delivery. Depending on the specific product implementation, enterprise messaging can offer disconnected operation, persistent messaging, internal acknowledgment of message receipt, and additional transactional recovery and message redelivery options.