Transport : web transport [Specification: CID protocol]

Transport : web transport

Once an available process selected by the client, the transport declaration defines how client and server must communicate together. The first section of this chapter defines how a client must determine process/transport compliance.

The selection of a process/transport couple is left to the client. It could automate the selection or build a GUI to delegate this choice to the user.

These specification only defines one transport possibilities : web transport which use a various web standard such as HTTP requests, HTTP authentication or cookies.

Cid extensions could defines new transport modalities (see the next section for more details).

Metadata and properties⚓

Transports must define a way to communicate properties between client and server. A property is a basic pair of key-value. Metadata are considered as document properties. A transport could define its own properties.

web transport attributes⚓

A web transport declaration could contains three attributes:

an id attribute to bind processes to one or more specific transports (see the first section of this chapter for more details);
a sessionProperties attribute;
a needCookies attribute.

Session properties⚓

The sessionProperties attribute must contain a list of one or more properties names. A session property could be returned by the server at any step of the process and must then be sent by client for the following steps.

Cookies declaration⚓

The needCookies attribute must contain a boolean value. A client which executes a process through a web transport that needs cookies itself must support this standard.

Authentication⚓

The authentication element is required in the web transport definition. It could be empty or contain one or more of basic, web (or no authentication) elements.

An empty authentication element means that no authentication scheme is required to use this transport definition. When this element has one or more children, the client must respect the requirement of one of them in order to use this transport definition.

Basic HTTP authentication⚓

Declaration⚓

The declaration of a Basic HTTP authentication contains only the basicHttp element.

<cid:authentications>
    <cid:basicHttp/>
</cid:authentications>

<cid:authentications>
    <cid:basicHttp/>
</cid:authentications>

Implementation⚓

When a web transport declaration contains a basic HTTP authentication scheme, the server must accept basic HTTP authentication for each request that could regularly be sent with this transport following process/transport compatibility defined in the first section of this chapter.

When a client select a Basic HTTP authentication scheme, it must send a authorization header in each request of the selected process.

Web authentication⚓

Declaration⚓

The declaration of a web authentication contains a webAuthentication element and an URL attribute.

<cid:authentications>
  <cid:webAuthentication  url="http://example.com/auth"/> 
</cid:authentications> 

<cid:authentications>
  <cid:webAuthentication  url="http://example.com/auth"/> 
</cid:authentications>

Implementation⚓

The server must furnish an authentication web page at the location specified in the URL attribute.

This page must be loaded by the client following the web interaction transport modalities (see further on this section).

At the end of the web authentication interaction, the server must send a message (following the HTML 5 post message API) containing a cidAuth property in the data part of the message. The authorized values of this property are succeeded and failed. This message must be considered by the client as the end interaction message (see web interact for further detail on end interaction mechanism).

Warning

A web authentication required the definition of at least one web interaction request.

No authentication⚓

Declaration⚓

The declaration of a public access is declared by a single noAuthentication element.

<cid:authentications>
    <cid:webAuthentication url="http://example.com/auth"/>
    <cid:noAuthentication/>
</cid:authentications> 

<cid:authentications>
    <cid:webAuthentication url="http://example.com/auth"/>
    <cid:noAuthentication/>
</cid:authentications>

Implementation⚓

The noAuthentication element does not required any specific implementations for the server or client side.

Example

The noAuthentication element allows a manifest to declare only one transport for either a public and a restricted access.

Web exchange⚓

The webExchange element defines how the exchange steps and system-oriented wait must be processed by the client and the server. The definition of a webExchange element is composed of several request definitions. Each request must define a HTTP method and a way to send params.

Defining a request⚓

In a web exchange context, the method attribute of a request could have the GET, POST;application/x-www-form-urlencoded or POST;multipart/form-data values. It defines the HTTP method that the client must use to communicate with the server. In the case of a POST HTTP request, the method contains also the kind of form that is available to the client.

The properties attribute could contains the header and queryString values for a GET HTTP request plus the post values for the POST HTTP requests.

ExampleExample of full webExchange declaration⚓

This example is called full because the server implements all the possibilities of exchange transports.

<cid:webExchange>
    <cid:request method="GET" properties="header queryString"/>
    <cid:request method="POST;application/x-www-form-urlencoded" properties="queryString header post"/>
    <cid:request method="POST;multipart/form-data" properties="header queryString post"/>
</cid:webExchange>

<cid:webExchange>
    <cid:request method="GET" properties="header queryString"/>
    <cid:request method="POST;application/x-www-form-urlencoded" properties="queryString header post"/>
    <cid:request method="POST;multipart/form-data" properties="header queryString post"/>
</cid:webExchange>

Implementation requirement⚓

In order to process an exchange step, the client must select one of the defined requests. The client must then select a method to send the properties in the properties attribute of the selected request.

Client requirement
properties\HTTP method	GET	POST;application/x-www-form-urlencoded	POST;multipart/form-data
header	the client must send a HTTP GET request and store the key/value of all the properties in the header of the request.	the client must send a HTTP POST request and store the key/value of all the properties in the header of the request.	the client must send a HTTP POST request and store the key/value of all the properties in the header of the request.
queryString	the client must send a HTTP GET request and store the key/value of all the properties in the URL as query string.	the client must send a HTTP POST request and store the key/value of all the properties in the URL as query string.	the client must send a HTTP POST request and store the key/value of all the properties in the URL as query string.
post		the client must send a HTTP POST request and store the key/value of all the properties in a url-encoded form.	the client must send a HTTP POST request and store the key/value of all the properties in a form-data.

The optional metadata or session properties returned by the server must be sent in the body or the response in a json object.

Web Interact⚓

The webInteract element defines how the interact steps and user-oriented wait must be processed by the client and the server. The definition of a webInteract element is composed of several request definitions. Each request must define a HTTP method and a way to send params.

Defining a request⚓

In a web interact context, the method attribute of a request could have the GET, POST;application/x-www-form-urlencoded or POST;multipart/form-data values. It defines the HTTP method that the client must use to communicate with the server. In the case of a POST HTTP request, the method contains also the kind of form that is available to the client.

The properties attribute could contains the header and queryString values for a GET HTTP request plus the post values for the POST HTTP requests.

ExampleExample of full webInteract declaration⚓

This example is called full because the server implements all the possibilities of exchange transports.

<cid:webExchange>
    <cid:request method="GET" properties="header queryString"/>
    <cid:request method="POST;application/x-www-form-urlencoded" properties="queryString header post"/>
    <cid:request method="POST;multipart/form-data" properties="header queryString post"/>
</cid:webExchange>

<cid:webExchange>
    <cid:request method="GET" properties="header queryString"/>
    <cid:request method="POST;application/x-www-form-urlencoded" properties="queryString header post"/>
    <cid:request method="POST;multipart/form-data" properties="header queryString post"/>
</cid:webExchange>

Implementation requirement⚓

In order to process an interact step, the client must select one of the defined requests. The client must then select a method to send the properties in the properties attribute of the selected request.

Client requirement
properties\HTTP method	GET	POST;application/x-www-form-urlencoded	POST;multipart/form-data
header	the client must send a HTTP GET request and store the key/value of all the properties in the header of the request.	the client must send a HTTP POST request and store the key/value of all the properties in the header of the request.	the client must send a HTTP POST request and store the key/value of all the properties in the header of the request.
queryString	the client must send a HTTP GET request and store the key/value of all the properties in the URL as query string.	the client must send a HTTP POST request and store the key/value of all the properties in the URL as query string.	the client must send a HTTP POST request and store the key/value of all the properties in the URL as query string.
post		the client must send a HTTP POST request and store the key/value of all the properties in a url-encoded form.	the client must send a HTTP POST request and store the key/value of all the properties in a form-data.

The result of the server must be a web page neutrally displayed in a web frame by the client. The client must then let the user in direct interaction with the server. Once the interaction is done, the web page must send an message through the postMessage API. This message must contain the metadata and properties returned by the server and a cidInteraction property set to ended or aborted :

The value aborted means that the user wants to cancel the process and the client should close its CID GUI. The client can't continue the process after and aborted cidInteraction value.
The value ended means that the interaction was regularly closed. The client must close the interaction and continue the process.

Web Upload⚓

The webUpload element defines how upload steps and user-oriented wait must be processed by the client and the server. The definition of a webUpload element is composed of several request definitions. Each request must define a HTTP method and a way to send params.

Defining a request⚓

In a web interact context, the method attribute of a request could have the GET, PUT, POST or POST;multipart/form-data values. It defines the HTTP method that the client must use to communicate with the server. In the case of a POST HTTP request, the method contains also the kind of form that is available to the client.

The properties attribute could contains the header and queryString values for a GET or PUT HTTP request plus the post values for the POST;multipart/form-data HTTP request.

ExampleExample of full webUpload declaration⚓

This example is called full because the server implements all the possibilities of exchange transports.

<cid:webUpload>
    <cid:request method="GET" properties="header queryString"/>
    <cid:request method="PUT" properties="header queryString"/>
    <cid:request method="POST" properties="queryString header"/>
    <cid:request method="POST;multipart/form-data" properties="header queryString post"/>
</cid:webUpload>

<cid:webUpload>
    <cid:request method="GET" properties="header queryString"/>
    <cid:request method="PUT" properties="header queryString"/>
    <cid:request method="POST" properties="queryString header"/>
    <cid:request method="POST;multipart/form-data" properties="header queryString post"/>
</cid:webUpload>

Implementation requirement⚓

In order to process an upload step, the client must select one of the defined requests. The client must then select a method to send the properties in the properties attribute of the selected request.

Client requirement
properties\HTTP method	PUT	GET	POST	POST;multipart/form-data
header	the client must send a HTTP PUT request containing the file to upload in the request body and store the key/value of all the properties in the header of the request.	the client must send a HTTP GET request containing the file to upload in the request body and store the key/value of all the properties in the header of the request.	the client must send a HTTP POST request containing the file to upload in the request body and store the key/value of all the properties in the header of the request.	the client must send a HTTP POST request containing a form data which store the file to upload in a `cidContent` field and store the key/value of all the properties in the header of the request.
queryString	the client must send a HTTP PUT request containing the file to upload in the request body and store the key/value of all the properties in the URL as query string.	the client must send a HTTP GET request containing the file to upload in the request body and store the key/value of all the properties in the URL as query string.	the client must send a HTTP POST request containing the file to upload in the request body and store the key/value of all the properties in the URL as query string.	the client must send a HTTP POST request containing a form data which store the file to upload in a `cidContent` field and store the key/value of all the properties in the URL as query string.
post				the client must send a HTTP POST request containing a form data which store the file to upload in a `cidContent` field and the key/value of all the properties.

The optional metadata or session properties returned by the server must be sent in the body or the response in a json object.

WarningAsynchronous upload⚓

When the process declares an asynchronous upload, the server could return an HTTP 202 code to the upload request. The client must choose one of the system-oriented or user-oriented defined in the process.

A user-oriented wait must be processed exactly as an interaction step just after the upload. The URL is defined by the process and the transport layer must be conform to the webInteract declaration.

To process a system-oriented wait, the client must repeat a request to the URL defined in the process following the webExchange declaration while the server is responding an HTTP 202 response code. The final request must be responded by a 200 or server error response code. The interval between the requests should be chosen by the client.