Web Services Introduction

Common definitions

Hypermedia systems are systems where text, pictures, audio, video and other media are stored in network hosts and connected through hyperlinks. The web is the example of hypermedia system.

The TCP-IP protocol stack makes it possible the data communication within a network of computer. The protocol stack is arranged in abstraction layers. From lowest to highest, the layers are: the link layer (for communication within a single network segment or link) the internet layer (for communication between independent networks) the transport layer (for communication host-to-host) and the application layer (for communication between two running application programs or processes: for example a client and a server). - (Internet_protocol_suite on wikipedia)

The HyperText Transfer Protocol or HTTP is an application-level protocol for hypermedia information systems.
HTTP is used by the World Wide Web with Hypertext to transfer data from servers to clients. HTTP is a generic protocol which can be used for many tasks beyond hypertext (such as Domain Name System and distributed object systems, like CORBA) through extension of its request methods, error codes and headers. (HTTP on wikipedia, HTTP on mozilla , rfc2616)

In computer networking, a communication channel is a logical connection that allows to transport information, from transmitters to receivers. A communication endpoint is an abstract object or interface that is the final point of a communication path; the transmitter writes to the endpoint and the receiver reads from the endpoint. For example, in operating systems, a software port is a communication endpoint managed by a computer's operating system, which identifies a specific process or a type of network service.

Web Service definitions

• A web service is a distributed software whose components can be deployed and executed on distinct devices.
• A web service consists of a service (a.k.a. producer) and a client (a.k.a. consumer or requester).

Web Service compared to Website

• both web services and websites are examples of distributed systems.
• websites deliver HMTL payloads whereas web services deliver XML or JSON payloads

Web service terminology

• endpoint: a web service endpoint is an association between a binding and a network address, specified by a URI, that may be used to communicate with an instance of a service.
• message: the basic unit of communication between a web service and a requester; data to be communicated to or from a web service as a single logical transmission.
• operation: a description of an action supported by the service; a set of messages related to a single web service action.
• synchronous: an interaction is said to be synchronous when the participating agents must be available to receive and process the associated messages from the time the interaction is initiated until all messages are actually received or some failure condition is determined.
• asynchronous: an interaction is said to be asynchronous when the associated messages are chronologically and procedurally decoupled.

Web Service communication layer

• A web service typically communicates over HTTP. A web service over HTTP is a web service that uses HTTP to transport web service messages (we say that HTTP protocol and HTTP messages are infrastructure). HTTP messages follow four kinds of conversational pattern: request/response, solicit/response, one-way and subscribe/notify
• the communication payloads are structured text, usually XML or JSON documents. XML and JSON are web service data interchange formats that provide an intermediary level and handle the differences in data types between different programming languages.

Web Service architecture

• The architecture of a simple web service is a client and a server.
• The architecture of a complicated web service have many clients and a service composed of other services.
• Example: an e-commerce service can be composed of multiple software components (each hosted on a separate web server) and any combination of PCs, tablets, mobile phones and other networked devices may host programs that make requests to the service.

Web services come in two flavors: SAOP-based and REST-style.

• SOAP is an XML dialect with a grammar that specifies the structure that documents must follow in order to be accepted as SOAP messages. SOAP-based services are transport neutral, but HTTP is the most common trasport for SOAP-based services
• REST-style services use HTTP not only as service transport protocol but also as service messaging system.

Why using web services?

• interoperability: clients and services can interact despite differences in programming languages, operating systems and hardware platforms.
• system integration: web services offers software integration for legacy system or databases. For example, you can write a web service that integrates with a legacy system written in COBOL or a web service that integrates with a RDBMS.

REST

Common definitions

A resource is anything that has identity. Examples of resources are an electronic document, an image file, a service (such as "today's weather report") and a collection of other resources. Not all resources are network "retrievable", for example: human beings, corporations and paper books.

A URI (Uniform Resource Identifier) is a sequence of characters that identifies a logical or physical resource.
URI can be classified in Name, Locator or both.

• A "Uniform Resource Locator" (URL) is a URI that, in addition to identifying a resource, allows to retrieve a representation of the resource from a server, by specifying both its access mechanism and network location.
  For example the URL = https://en.wikipedia.org/wiki/Dolphin references a resource identified by the name /wiki/Dolphin, whose representation can be fetched via HTTP from a server with a domain name en.wikipedia.org
• A "Uniform Resource Name" (URN) is a URI that serves as a unique name for a resource, independent of where the resource currently resides and persistent even when the resource becomes unavailable. A URN gives no means to access a resource. Historically, the term URN is also used to refer to any other URIs with the properties of a name.
  For example the International Standard Book Number (ISBN) system defines identifier for books as string composed of 10 digits.

A URN may be compared to a person's name, whereas a URL may be compared to a person's house address.

URI Syntax:

URI = scheme : [ //authority ] path [ ? query ] [ # fragment ]
      where authority = [ userinfo @ ] host [ : port ]

The URI comprises:

• A non-empty scheme component followed by a colon (:)
• An optional authority component preceded by two slashes (//), comprising:
  • An optional userinfo subcomponent that may have the format "username:password", followed by an at symbol (@).
  • A host subcomponent, consisting of either a registered name or an IP address.
  • An optional port subcomponent preceded by a colon (:)
• A path component, consisting of a sequence of path segments separated by a slash (/). A path is always defined for a URI, though the defined path may be empty (zero length).
• An optional query component preceded by a question mark (?), containing a query string of data.
• An optional fragment component preceded by a hash (#).

Example: URI and its component parts:

URI = https://en.wikipedia.org/wiki/Dolphin#Anatomy
where:
scheme    = https
authority = en.wikipedia.org
path      = /wiki/Dolphin
fragment  = Anatomy

URI = mailto:john77@apache.org 
where:
scheme = mailto
path   = john77@apache.org 

URI = tel:+39-347-957-0202
where:
scheme = tel
path   = +39-347-957-0202

URI = urn:isbn:1234567890
where:
scheme = urn
path   = isbn:1234567890

(URI rtc on ietf.org Internet-Engineering-Task-Force - URI on wikipedia.org)

REST definition

• REST is an acronym for REpresentational State Transfer
• REST is a software architectural style for hypermedia systems; the web is an example of hypermedia system
• REST principles enable the building of software systems that are known as REST-style or RESTful web service

RESTful systems and HTTP

• In the web, HTTP is both a transport protocol and a messaging system
• HTTP requests and responses are the messages (https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages)
• HTTP payloads can be typed using the MIME type system (https://developer.mozilla.org/en-US/docs/Glossary/MIME_type)
• HTTP response status codes notify the requester about whether the request was successful or not.

Web Resource

• REST centers around the concept of web resource (web resource on wikipedia)
• a web resource is a piece of information accessible on the web through HTTP, because a URI identifies the resource by name
  For example, the Pink Floyd rock band is a resource.
• Resources may have one or more representations. Those representations in the web are MIME typed.
  For example, the page on wikipedia about Pink Floyd is a representation that has text/html MIME type, an audio file on spotify about Pink Floyd is a representation that has audio/mpeg MIME type.
• Resources have a state which may change over time and resource’s representations hold this state.
  For example, Pink Floyd recorded many albums during their career. The Pink Floyd’s page should hold the discography state of Pink Floyd resource
• Resources can be persisted on a data store.

RESTful requests target a resource

• when a web service access a resource, the requester receives a representation of the resource. If the retrieve request succeeds, a typed representation of resource (ex. text/html) is transferred from the machine hosting the service.
• When a RESTful client accesses a resource it does two things: names the resource by giving its URI and specifies the verb (HTTP method) that indicates the operation the client wishes to do (create a new resource, retrieve a resource, update an existing resource and delete an existing resource)
• In practice, a RESTful request contains the name of the resource and the client operation on the resource

  RESTful request ≡ resource’s URI + client operation

In the REST, HTTP works as an API

• HTTP has its methods: each method corresponds to a CRUD operation.

  HTTP method	CRUD operation
  POST	Create
  GET	Retrieve
  UPDATE	Update
  DELETE	Delete

• HTTP has its response code. For example 200 Response Success, 404 Not Found and 500 Internal Server Error
• To sum up, HTTP gives methods and MIME types to client requests and status codes and MIME types to service responses.

HTTP as an API

Using HTTP as an API makes less distinct the differences between websites returning html and web services returning XML or JSON payloads.

• a GET request for the URI /products is equivalent to a GET request for a URI /products.html: they return the same HTML list of products.
• a GET requests for the URI /products.json return a JSON list of products
• a GET request for the URI /products.xml return an XML list of products

Using HTTP as an API allows to combine URIs and HTTP methods to form RESTful routes:

• the table below summarizes the conventions for RESTful routes

  Route Name	HTTP verb	URI path	Operation
  Index	GET	/products	Read all products
  Show	GET	/products/:id	Read a product with the given id
  New	GET	/products/new	return an HTML form for creating a new product
  Create	POST	/products	Create a new product
  Edit	GET	/products/:id/edit	Return an HTML form for editing a product with given id
  Update	PUT	/products/:id	Update a product with the given id
  Destroy	DELETE	/products/:id	Delete a product with the given id

• each route is a pair: an HTTP verbs plus a URI path
• each route expresses which operation should be performed on which resource

References

Network Basis on Wikibooks
Web Services Description Language (WSDL) on W3C
Web Service Glossary on W3C
Representational State Transfer on Wikipedia