Extended Hypertext Transfer Protocol (XHTTP) 1.0
Specification Document 1 March 2011
- This version:
- http://www.xhttp.org/specification
- Latest version:
- http://www.xhttp.org/specification
- Author:
© Copyright 2010-2024 James Watts. All rights reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to author(s) or other individuals or organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by the author(s) or their successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and THE AUTHOR(S) DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Abstract
This specification describes the Extended Hypertext Transfer Protocol (XHTTP), an extension to the Hypertext Transfer Protocol, allowing for distributed application programming interfaces over a network.
Status of this Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document.
This is the first version of the XHTTP specification. It is produced as an authoritative documentation of the status and use of the Extended Hypertext Transfer Protocol (XHTTP).
This document assumes the reader has knowledge of and a basic understanding of the Hypertext Transfer Protocol (HTTP) 1 and the Extensible Markup Language (XML) 2.
See the changes section for details of the changes in this version of the specification.
Table of Contents
- Introduction
- Requirements
- Terminology
- Conventions
- Example
- Schema
- Data Types
- Exception Codes
- Modes
- Status Codes
- Request Headers
- Response Headers
- References
- Acknowledgments
- Changes
1. Introduction
With the introduction of specifications such as SOAP 3 (previously known as the Simple Object Access Protocol), the Web Services Description Language (WSDL) 4 and Universal Description Discovery and Integration (UDDI) 5, web services have become a major part of distributed programming and interconnected systems, contributing greatly to the rise of software orientated architectures (SOA) 6. However, as important as these technologies have been to the evolution of software development and the advance of the Internet, they still remain overly complex and network resource intensive. Many alternatives have appeared, such as XML-RPC 7, and others using JSON (JavaScript Object Notation) 8, which offer a similar cominucation process, yet at the sacrifice of losing the framework architecture.
This specification proposes a solution which builds on and extends the Hypertext Transfer Protocol (HTTP), providing a simple method for exposing versioned server-side application programming interfaces (API), with simple configuration requirements and minimal transport overhead.
2. Requirements
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 9.
An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant".
3. Terminology
This specification uses a number of terms to refer to the roles played by participants in, and objects of, the HTTP communication.
- connection: A transport layer virtual circuit established between two programs for the purpose of communication.
- message: The basic unit of HTTP communication, consisting of a structured sequence of octets matching the syntax defined in section 4 and transmitted via the connection.
- request: An HTTP request message, as defined in section 5 of the Hypertext Transfer Protocol (HTTP) 1.
- response: An HTTP response message, as defined in section 6 of the Hypertext Transfer Protocol (HTTP) 1.
- resource: A network data object or service that can be identified by a URI, as defined in section 3.2 of the Hypertext Transfer Protocol (HTTP) 1. Resources may be available in multiple representations (e.g. multiple languages, data formats, size, and resolutions) or vary in other ways.
- entity: The information transferred as the payload of a request or response. An entity consists of metainformation in the form of entity-header fields and content in the form of an entity-body, as described in section 7 of the Hypertext Transfer Protocol (HTTP) 1.
- representation: An entity included with a response that is subject to content negotiation, as described in section 12 of the Hypertext Transfer Protocol (HTTP) 1. There may exist multiple representations associated with a particular response status.
- content negotiation: The mechanism for selecting the appropriate representation when servicing a request, as described in section 12 of the Hypertext Transfer Protocol (HTTP) 1. The representation of entities in any response can be negotiated (including error responses).
- variant: A resource may have one, or more than one, representation(s) associated with it at any given instant. Each of these representations is termed a 'varriant'. Use of the term `variant' does not necessarily imply that the resource is subject to content negotiation.
- client: A program that establishes connections for the purpose of sending requests.
- user agent: The client which initiates a request. These are often browsers, editors, spiders (web-traversing robots), or other end user tools.
- server: An application program that accepts connections in order to service requests by sending back responses. Any given program may be capable of being both a client and a server; our use of these terms refers only to the role being performed by the program for a particular connection, rather than to the program's capabilities in general. Likewise, any server may act as an origin server, proxy, gateway, or tunnel, switching behavior based on the nature of each request.
- origin server: The server on which a given resource resides or is to be created.
- proxy: An intermediary program which acts as both a server and a client for the purpose of making requests on behalf of other clients. Requests are serviced internally or by passing them on, with possible translation, to other servers. A proxy MUST implement both the client and server requirements of this specification. A "transparent proxy" is a proxy that does not modify the request or response beyond what is required for proxy authentication and identification. A "non-transparent proxy" is a proxy that modifies the request or response in order to provide some added service to the user agent, such as group annotation services, media type transformation, protocol reduction, or anonymity filtering. Except where either transparent or non-transparent behavior is explicitly stated, the HTTP proxy requirements apply to both types of proxies.
- gateway: A server which acts as an intermediary for some other server. Unlike a proxy, a gateway receives requests as if it were the origin server for the requested resource; the requesting client may not be aware that it is communicating with a gateway.
- tunnel: An intermediary program which is acting as a blind relay between two connections. Once active, a tunnel is not considered a party to the HTTP communication, though the tunnel may have been initiated by an HTTP request. The tunnel ceases to exist when both ends of the relayed connections are closed.
- cache: A program's local store of response messages and the subsystem that controls its message storage, retrieval, and deletion. A cache stores cacheable responses in order to reduce the response time and network bandwidth consumption on future, equivalent requests. Any client or server may include a cache, though a cache cannot be used by a server that is acting as a tunnel.
- cacheable: A response is cacheable if a cache is allowed to store a copy of the response message for use in answering subsequent requests. The rules for determining the cacheability of HTTP responses are defined in section 13. Even if a resource is cacheable, there may be additional constraints on whether a cache can use the cached copy for a particular request.
- first-hand: A response is first-hand if it comes directly and without unnecessary delay from the origin server, perhaps via one or more proxies. A response is also first-hand if its validity has just been checked directly with the origin server.
- explicit expiration time: The time at which the origin server intends that an entity should no longer be returned by a cache without further validation.
- heuristic expiration time: An expiration time assigned by a cache when no explicit expiration time is available.
- age: The age of a response is the time since it was sent by, or successfully validated with, the origin server.
- freshness lifetime: The length of time between the generation of a response and its expiration time.
- fresh: A response is fresh if its age has not yet exceeded its freshness lifetime.
- stale: A response is stale if its age has passed its freshness lifetime.
- semantically transparent: A cache behaves in a "semantically transparent" manner, with respect to a particular response, when its use affects neither the requesting client nor the origin server, except to improve performance. When a cache is semantically transparent, the client receives exactly the same response (except for hop-by-hop headers) that it would have received had its request been handled directly by the origin server.
- validator: A protocol element (e.g., an entity tag or a Last-Modified time) that is used to find out whether a cache entry is an equivalent copy of an entity.
- upstream/downstream: Upstream and downstream describe the flow of a message: all messages flow from upstream to downstream.
- inbound/outbound: Inbound and outbound refer to the request and response paths for messages: "inbound" means "traveling toward the origin server", and "outbound" means "traveling toward the user agent".
4. Conventions
All of the mechanisms specified in this document are described in both prose and an augmented Backus-Naur Form (BNF) similar to that used by RFC 822 10. Implementors will need to be familiar with the notation in order to understand this specification. The augmented BNF includes the following constructs:
name = definition
The name of a rule is simply the name itself (without any enclosing "<" and ">") and is separated from its definition by the equal "=" character. White space is only significant in that indentation of continuation lines is used to indicate a rule definition that spans more than one line. Certain basic rules are in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle brackets are used within definitions whenever their presence will facilitate discerning the use of rule names.
"literal"
Quotation marks surround literal text. Unless stated otherwise, the text is case-insensitive.
rule1 | rule2
Elements separated by a bar ("|") are alternatives, e.g., "yes | no" will accept yes or no.
(rule1 rule2)
Elements enclosed in parentheses are treated as a single element. Thus, "( elem ( foo | bar ) elem )" allows the token sequences "elem foo elem" and "elem bar elem".
*rule
The character "*" preceding an element indicates repetition. The full form is "<n>*<m>element" indicating at least <n> and at most <m> occurrences of element. Default values are 0 and infinity so that "*( element )" allows any number, including zero; "1*element" requires at least one; and "1*2element" allows one or two.
[rule]
Square brackets enclose optional elements; "[ foo bar ]" is equivalent to "*1( foo bar )".
N rule
Specific repetition: "<n>( element )" is equivalent to "<n>*<n>( element )"; that is, exactly <n> occurrences of (element). Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three alphabetic characters.
#rule
A construct "#" is defined, similar to "*", for defining lists of elements. The full form is "<n>#<m>element" indicating at least <n> and at most <m> elements, each separated by one or more commas (",") and OPTIONAL linear white space (LWS). This makes the usual form of lists very easy; a rule such as:
( *LWS element *( *LWS "," *LWS element ) )
can be shown as:
1#element
Wherever this construct is used, null elements are allowed, but do not contribute to the count of elements present. That is, "( element ), , ( element ) " is permitted, but counts as only two elements. Therefore, where at least one element is required, at least one non-null element MUST be present. Default values are 0 and infinity so that "#element" allows any number, including zero; "1#element" requires at least one; and "1#2element" allows one or two.
; comment
A semi-colon, set off some distance to the right of rule text, starts a comment that continues to the end of line. This is a simple way of including useful notes in parallel with the specifications.
implied *LWS
The grammar described by this specification is word-based. Except where noted otherwise, linear white space (LWS) can be included between any two adjacent words (token or quoted-string), and between adjacent words and separators, without changing the interpretation of a field. At least one delimiter (LWS and/or separators) MUST exist between any two tokens (for the definition of "token" below), since they would otherwise be interpreted as a single token.
Additionally, the following rules are used throughout this specification to describe basic parsing constructs. The US-ASCII coded character set is defined by ANSI X3.4-1986 11.
OCTET = <any 8-bit sequence of data>
CHAR = <any US-ASCII character (octets 0 - 127)>
UPALPHA = <any US-ASCII uppercase letter "A".."Z">
LOALPHA = <any US-ASCII lowercase letter "a".."z">
ALPHA = UPALPHA | LOALPHA
DIGIT = <any US-ASCII digit "0".."9">
CTL = <any US-ASCII control character
(octets 0 - 31) and DEL (127)>
CR = <US-ASCII CR, carriage return (13)>
LF = <US-ASCII LF, linefeed (10)>
SP = <US-ASCII SP, space (32)>
HT = <US-ASCII HT, horizontal-tab (9)>
<"> = <US-ASCII double-quote mark (34)>
HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all protocol elements except the entity-body (see appendix 19.3 of the Hypertext Transfer Protocol (HTTP) 1 for tolerant applications). The end-of-line marker within an entity-body is defined by its associated media type, as described in section 3.7 of the Hypertext Transfer Protocol (HTTP) 1.
CRLF = CR LF
HTTP/1.1 header field values can be folded onto multiple lines if the continuation line begins with a space or horizontal tab. All linear white space, including folding, has the same semantics as SP. A recipient MAY replace any linear white space with a single SP before interpreting the field value or forwarding the message downstream.
LWS = [CRLF] 1*( SP | HT )
The TEXT rule is only used for descriptive field contents and values that are not intended to be interpreted by the message parser. Words of *TEXT MAY contain characters from character sets other than ISO-8859-1 12 only when encoded according to the rules of RFC 2047 13.
TEXT = <any OCTET except CTLs,
but including LWS>
A CRLF is allowed in the definition of TEXT only as part of a header field continuation. It is expected that the folding LWS will be replaced with a single SP before interpretation of the TEXT value.
Hexadecimal numeric characters are used in several protocol elements.
HEX = "A" | "B" | "C" | "D" | "E" | "F"
| "a" | "b" | "c" | "d" | "e" | "f" | DIGIT
Many HTTP/1.1 header field values consist of words separated by LWS or special characters. These special characters MUST be in a quoted string to be used within a parameter value (as defined in section 3.6 of the Hypertext Transfer Protocol (HTTP) 1).
token = 1*<any CHAR except CTLs or separators>
separators = "(" | ")" | "<" | ">" | "@"
| "," | ";" | ":" | "\" | <">
| "/" | "[" | "]" | "?" | "="
| "{" | "}" | SP | HT
Comments can be included in some HTTP header fields by surrounding the comment text with parentheses. Comments are only allowed in fields containing "comment" as part of their field value definition. In all other fields, parentheses are considered part of the field value.
comment = "(" *( ctext | quoted-pair | comment ) ")"
ctext = <any TEXT excluding "(" and ")">
A string of text is parsed as a single word if it is quoted using double-quote marks.
quoted-string = ( <"> *(qdtext | quoted-pair ) <"> ) qdtext = <any TEXT except <">>
The backslash character ("\") MAY be used as a single-character quoting mechanism only within quoted-string and comment constructs.
quoted-pair = "\" CHAR
5. Example
The following is an example of an XHTTP request and a detailed description of the process to generate the response:
Step 1: The client makes a request to a server located at a specific URI:
GET http://example.com/web-services/xhttp?quantity=120&category=co HTTP/1.1
The request includes the following headers:
Host: example.com Version: 1.0 Service: coffee;1.2 Action: order Arguments: quantity;3,category;4 Encoding: x-user-defined
Step 2: The server checks that the XHTTP version the client specified in the value of the Version header is equal or inferior to the version available on the server. If the server confirms that the versions are compatible it proceeds to check the XML schema for the following criteria:
- The name and version specified in the Service header corresponds to a service available on this server.
- The name specified in the Action header corresponds to an action available on the requested service.
- The values specified in the Arguments header and the URI correspond to the arguments specified as required by the action.
Step 3: The server processes the request and loads the specified service according to the requested service version.
Step 4: The service performs the requested action with the arguments given in the query string part of the URI translated to the native data types of the implementation language using the values specified in the Arguments header.
Step 5: The action may make secondary requests to other servers and build the response based on the values received from those servers.
Once this process has completed the server will return the response to the client:
HTTP/1.1 200 OK Date: Thu, 21 Nov 2024 08:18:33 GMT Return: 5 ['Order Complete',true,4556783]
The Return header notifies the client of the data type of the value returned in the body of the response.
If an error should occur during the process and is not caught but the action before-hand, an exception would be thrown as the response, detailing the error in the Exception header:
HTTP/1.1 550 Exception Date: Thu, 21 Nov 2024 08:18:33 GMT Exception: Something went wrong;3
6. Schema
The XHTTP schema defines a service, the versions of its API, detailed information on each version, and the actions available for each version, including exceptions, arguments and return values of each individual action. The XML Schema Definition (XSD) 14 for the XHTTP schema can be found at the following location: http://www.xhttp.org/schema.
The root element of the XHTTP schema is <xhttp>. This element specifies the namespace and has a single REQUIRED attribute, version. The value of this attribute specifies the minimum version of the XHTTP protocol that the service requires. This version MUST be equal or lower than the version implemented by the XHTTP server. If the minimum version of the service is greater than the version implemented by the server, a 551 XHTTP Version Not Supported status MUST be returned by the server upon any request to that service.
<xhttp xmlns:xhttp="http://www.xhttp.org/schema" version="1.0">
The XHTTP schema can define n versions of a service using the <xhttp:schema> element. This element has a single REQUIRED attribute, version. The value of this attribute specifies the version number of the service API. This number MUST be composed of a major integer and a minor integer, separated by a ".". For example, "1.0".
<xhttp:schema version="1.3">
...
</xhttp:schema>
Each version of a service can contain details about itself, defined using the <xhttp:info> element. It is purely informative, and SHOULD NOT affect the behaviour of the service. This element has 2 REQUIRED attributes, name and value.
The value of the name attribute MUST be a string, and specifies the semantic nature of the information contained in the value of the value attribute, which MAY contain any value.
The content of both of these attributes SHOULD use the correct character encoding.
<xhttp:info name="something" value="This is some information"/>
The <xhttp:schema> element can contain n <xhttp:info> elements, and the value of the name attributes of these MAY contain, yet are not limited to, the following predefined values:
- service: The name of the XHTTP service.
- host: The full URL to the XHTTP server hosting the service.
- port: The port number the server listens on.
- author: The author(s) of the XHTTP service.
- email: A contact email address.
- link: A URL for more information.
- version: The version of the XHTTP service.
- build: The build version or identifier.
Each action in the XHTTP schema is represented using the <xhttp:action> element. This element has 2 REQUIRED attributes, name and function.
The value of the name attribute MUST be a string which complies with the format restrictions set by the Action header, and defines the value which is specified by the request to perform the action.
The value of the function attribute MUST be a string, and specifies the identifier of the function to execute in the implementation programming language.
The content of both of these attributes SHOULD use the correct character encoding.
<xhttp:action name="run" function="run_action">
...
</xhttp:action>
An <xhttp:action> element MUST contain the REQUIRED element <xhttp:return>, but also MAY contain 0 or n of the OPTIONAL child elements <xhttp:exception> and <xhttp:argument>.
The <xhttp:exception> element defines an exception thrown by the action. This element has 2 REQUIRED attributes, code and message.
The value of the code attribute MUST be an integer, and defines the numeric code given by the exception.
The value of the message attribute MUST be a string, and defines the message given by the exception. The content of this attribute SHOULD use the correct character encoding.
An <xhttp:action> element MAY contain 0 or n <xhttp:exception> elements.
<xhttp:exception code="4" message="Specified value out of range"/>
The <xhttp:argument> element defines an argument expected by the action. This element has 2 REQUIRED attributes, name and type, and 4 OPTIONAL attributes, use, default, validate and modifiers.
The value of the name attribute MUST be a string, and defines the value that MUST be specified by the Arguments header to identify the argument. The content of this attribute SHOULD use the correct character encoding.
The value of the type attribute MUST be one of the integers defined in section 7, and defines the data type that SHOULD be specified by the argument in the Arguments header.
If specified, the value of the use attribute MUST be a string, and defines if the argument is optional (the client MAY optionally send the argument) or is required (the client MUST send the argument). The value of this attribute SHOULD be 1 of the following values: "optional" or "required". If the use attribute is not specified, or any other value is given, the "optional" value MUST be assumed. If the client does not pass all the arguments specified as "required" by the XHTTP schema a 455 Missing Arguments status MUST be returned by the server.
If specified, the value of the default attribute MUST be a value which complies with the format required by the data type specified by the value of the type attribute. If the argument is optional (see details of the use attribute) and has not been sent by the client, the value of the argument in the server implementation MUST resolve to the value of the default attribute and thus translate to it's corresponding data type and value in the implementation programming language.
If specified, the value of the validate attribute MUST be a string, and defines a Perl-compatible regular expression (PCRE) 15 that the value of argument must match in order to be considered valid. Additionally, a modifiers attribute MAY be specified to define the modifiers to apply to the regular expression. If a modifiers attribute is not specified the server MUST assume no modifiers are to be applied. If the client sends an argument which has a value that does not pass the regular expression of the validate attribute a 456 Invalid Argument status MUST be returned by the server.
The content of the name, use, default, validate and modifiers attribute SHOULD use the correct character encoding.
An <xhttp:action> element MAY contain 0 or n <xhttp:argument> elements.
<xhttp:argument name="data" type="4" use="optional" default="foo" validate="[\w]+"/>
The <xhttp:return> element defines the data type of the value returned by the action in the body of the response. This element has 1 REQUIRED attribute, type. The value of this attribute MUST be one of the integers defined in section 7, and defines the data type that MUST be specified in Return header of the response, and applied accordingly to the value returned in the body of the response. An <xhttp:action> element MUST contain 1 <xhttp:return> element.
<xhttp:return type="2"/>
The full XHTTP schema for a service may look similar to the following:
<?xml version="1.0" encoding="UTF-8"?>
<xhttp xmlns:xhttp="http://www.xhttp.org/schema" version="1.0">
<xhttp:schema version="1.2">
<xhttp:info name="service" value="example"/>
<xhttp:info name="host" value="http://example.com/web-services/xhttp"/>
<xhttp:info name="port" value="80"/>
<xhttp:info name="author" value="James Watts (SOLFENIX)"/>
<xhttp:info name="email" value="jameswatts@solfenix.com"/>
<xhttp:info name="link" value="http://www.solfenix.com"/>
<xhttp:info name="version" value="1.2"/>
<xhttp:info name="build" value="20110401"/>
<xhttp:action name="test" function="test">
<xhttp:exception code="1" message="You must pass a string of text"/>
<xhttp:argument name="text" type="4" use="required"/>
<xhttp:return type="1"/>
</xhttp:action>
</xhttp:schema>
</xhttp>
7. Data Types
There are 10 data types, each with their default value, defined to identify the type of the value being received by the server or sent to the client. Data types are specified using a single integer value, which MUST be one of the following:
- 0: [Null] Discriminated null value. Defaults to an empty value (no value).
- 1: [Boolean] Boolean logical value (1 or 0). Defaults to 0.
- 2: [Integer] Whole number. Defaults to 0.
- 3: [Double] Double precision floating point number. Defaults to 0.0.
- 4: [String] String of characters. Defaults to an empty value (no value).
- 5: [Array] Array of values, storing no keys. Defaults to []. *
- 6: [Struct] Associative array or object. Defaults to {}. *
- 7: [Lambda] Anonymous or named function (reserved, currently unspecified). Defaults to {}. *
- 8: [Base64] Base64-encoded binary data. Defaults to an empty value (no value).
- 9: [DateTime] Date and time in ISO-8601 16 format. Defaults to the current date and time.
* Native values of these types MUST be encoded using JavaScript Object Notation (JSON) 8 in the query string of the request if an argument, or in the response body if a return value.
These data types have been defined to comply with the existing types defined by XML-RPC 7, for compatibility between specifications and to facilitate the migration of services bewteen XML-RPC 7 and XHTTP, and vice versa.
8. Exception Codes
The exception codes ranging from 100 to 199 are reserved for the protocol. This specification defines the following exception codes and messages to be used by the client or returned by the server in the Exception header:
- 101: Cannot process response if request not ready.
- 102: Cannot return value of incomplete response.
- 103: Redirection exception.
- 104: Client exception.
- 105: Server exception.
- 106: Missing required arguments. *
- 107: Invalid argument passed. *
- 108: Unknown exception.
- 109: Incompatible protocol version.
* These exceptions are defined for a client to pre-process arguments before sending a request. The server MUST use the 455 Missing Arguments and the 456 Invalid Argument status codes to notify that arguments are missing or are invalid.
Using these reserved exception codes for other purposes could cause unexpected results in protocol communication. It is advised to check that native errors thrown by the implementation programming language do not use a code within the reserved range.
9. Modes
The mode dictates the server on how to handle the request. In order to allow for future extensions to the XHTTP protocol the client MAY indicate to the server that the request MUST be handled per the specified value. If the Mode header is not found or does not contain a value, the server SHOULD assume perform as the requested mode by the client. This specification defines 4 modes to be sent by the client in the Mode header.
9.1. Version
If the value specified in the Mode header is version the server MUST return a JavaScript Object Notation (JSON) 8 representation of an array of schema versions available for the service specified in the Service header. Any schema version specified in the Service header MUST be ignored.
If the Service header is not found or does not contain a value, a 451 Service Not Specified status MUST be returned by the server. If a service by the name specified in the Service header does not exist, a 453 Service Not Found status MUST be returned by the server.
version = "[" #( DIGIT "." DIGIT ) "]"
9.2. Info
If the value specified in the Mode header is info the server MUST return a JavaScript Object Notation (JSON) 8 representation of an array of arrays for each info element defined in the XHTTP schema for the service and schema version specified in the Service header.
Each index of the primary array must be an array. Each of these secondry arrays define the info elements and MUST contain 2 indexes, the first containing the value of the name attribute as a string, and the second containing the value of the value attribute as a string.
If the Service header is not found or does not contain a value, a 451 Service Not Specified status MUST be returned by the server. If the service and/or schema version specified in the Service header do not exist, a 453 Service Not Found status MUST be returned by the server.
info = "[" #( "[" ALPHA "," TEXT "]" ) "]"
9.3. Schema
If the value specified in the Mode header is schema the server MUST return a JavaScript Object Notation (JSON) 8 representation of an array of arrays for all the action elements defined in the XHTTP schema for the service and schema version specified in the Service header.
Each index of the primary array must be an array. Each of these secondry arrays define the actions and MUST contain 4 indexes. The first index of the secondry array MUST contain the value of the name attribute as a string.
The second index of the secondry array MUST contain an array. If the action has exceptions, each index of this array MUST be an array with 2 indexes, the first containing the value of the message attribute as a string, and the second containing the value of the code attribute as an integer.
The third index of the secondry array MUST be an array. If the action has arguments, each index of this array MUST be an array with 3 indexes, the first containing the value of the name attribute as a string, the second containing the value of the type attribute as an integer, and the third containing the use of the argument as a boolean, "true" if the argument is required or "false" if the argument is optional or does not define the use attribute.
The forth index of the secondry array MUST be the value of the type attribute of the return element as an integer.
If the Service header is not found or does not contain a value, a 451 Service Not Specified status MUST be returned by the server. If the service and/or schema version specified in the Service header do not exist, a 453 Service Not Found status MUST be returned by the server.
schema = "[" #( "[" ALPHA ","
"[" #( "[" TEXT "," DIGIT "]" ) "]" ","
"[" #( "[" ALPHA "," DIGIT "," ( true | false ) "]" ) "]" ","
DIGIT "]" ) "]"
If an Action header is found and contains a value, the server MUST return the JavaScript Object Notation (JSON) 8 representation of an array for that specified action. If the specified action does not exist for the specified service and schema version, a 454 Action Not Found status MUST be returned.
schema = "[" ALPHA ","
"[" #( "[" TEXT "," DIGIT "]" ) "]" ","
"[" #( "[" ALPHA "," DIGIT "," ( true | false ) "]" ) "]" ","
DIGIT "]"
9.4. Perform
If the value specified in the Mode header is perform the server MUST process the action specified in the Action header for the service and schema version specified in the Service header. This MUST be done by matching the value specified in the Action header with a value defined in the name attribute of one of the action elements.
If the value specified as the version of the service is n.*, where n is the value specified as the major version, the * character MUST resolve to the maximum minor version available of the specified major version of that service. If the value specified as the version of the service is *.*, the version MUST resolve to the maximum (highest in value) version available for that service.
If the specified action does not exist for the specified service and schema version, a 454 Action Not Found status MUST be returned. If the server receives any arguments in Arguments header it MUST process and pass these to the function defined in the action element, else the server SHOULD process the function without arguments.
10. Status Codes
This specification defines additional HTTP status codes to compliment the extended funcionality of the protocol.
10.1. Client Error 4xx
Response status codes within the 400 range are intended for cases in which the client seems to have erred. These status codes are applicable to any request method.
10.1.1. 450 Mode Not Supported
The 450 Mode Not Supported status specifies that the value given in the Mode header does not identify a mode supported by the current version of the XHTTP specification implemented by this server.
10.1.2. 451 Service Not Specified
The 451 Service Not Specified status specifies that the Service header was not defined by the request or does not contain a value.
10.1.3. 452 Action Not Specified
The 452 Action Not Specified status specifies that the Action header was not defined by the request or does not contain a value.
10.1.4. 453 Service Not Found
The 453 Service Not Found status specifies that the value given in the Service header does not identify an XHTTP service on this server.
10.1.5. 454 Action Not Found
The 454 Action Not Found status specifies that the value given in the Action header is not defined by the specified version of the requested XHTTP service.
10.2. Server Error 5xx
Response status codes within the 500 range indicate cases in which the server is aware that it has erred or is incapable of performing the request. These response codes are applicable to any request method.
10.2.1. 550 Exception
The 550 Exception status specifies that an exception has been thrown by the action, and that the client SHOULD search for an Exception header in the response for detailed information.
10.2.2. 551 XHTTP Version Not Supported
The 551 XHTTP Version Not Supported status specfies that the requested XHTTP version is not currently supported by this server.
11. Request Headers
The following are XHTTP request headers which are sent addionally to the standard HTTP request headers.
11.1. Version Header
The value of the Version header specifies the minimum version of the XHTTP protocol that the server MUST support. If the server does not support the specified version or greater, a 551 XHTTP Version Not Supported status MUST be returned by the server.
version = "Version" ":" DIGIT [ "." DIGIT ] CRLF
11.2. Mode Header
The value of the Mode header specifies the mode the server MUST use. If the specified mode is not defined by the specification of the XHTTP version in use, a 450 Mode Not Supported status MUST be returned by the server. If the Mode header is not found or does not contain a value, the server MUST assume perform.
mode = "Mode" ":" ALPHA CRLF
11.3. Service Header
The value of the Service header specifies the name of the XHTTP service and, optionally, the schema version to load. If the Service header is not found or does not contain a value, a 451 Service Not Specified status MUST be returned by the server. If the value given does not match an existing service, a 453 Service Not Found status MUST be returned by the server. If the version is not specified in the Service header, the server MUST assume *.*. If the minor version is not specified in the Service header, the server MUST assume n.*, where n is the value specified as the major version.
service = "Service" ":" ALPHA [ ";" DIGIT [ "." DIGIT ] ] CRLF
11.4. Action Header
The value of the Action header specifies the name of the action to use or perform, and defined by the XHTTP schema of the service. If the name of the action given is not defined by the XHTTP schema of the service, a 454 Action Not Found status MUST be returned by the server. If the Action header is not found or does not contain a value, and is REQUIRED by the specified value given in the Mode header, a 452 Action Not Specified status MUST be returned by the server.
action = "Action" ":" ALPHA CRLF
11.5. Arguments Header
The value of the Arguments header defines a list of 0 or n arguments to be supplied to the action in the query string part of the URI. Each argument is composed of a name and a type. Each argument MUST specify a name, which MUST be identical to the parameter name given in the query string. If a type is not specified, the server SHOULD assume 0. For the definition of available data types see section 7.
If the client does not send an argument that is specified in the XHTTP schema of the service as required, a 455 Missing Arguments status MUST be returned by the server. If the client does not send an argument as a parameter in the query string of the URI, that has been specified in the Arguments header, a 456 Invalid Argument status MUST be returned by the server.
arguments = "Arguments" ":" #( ALPHA [ ";" DIGIT ] ) CRLF
11.6. Encoding Header
The value of the Encoding header specifies the encoding of the return value given in the body of the response. If the server cannot satisfy the requested encoding, a 412 Precondition Failed status MUST be returned by the server. If the Encoding header is not found or does not contain a value, the server SHOULD assume x-user-defined.
It should be noted that all server responses to an XHTTP request must have a content type of text/plain. The encoding refers to the character encoding applied to the body of the response, defined in the Content-Type header as the charset parameter.
encoding = "Encoding" ":" 1*<any CHAR or "-"> CRLF
12. Response Headers
The following are XHTTP response headers which are sent addionally to the standard HTTP response headers.
12.1. Return Header
The value of the Return header specifies the data type of the return value in the body of the response. The value MUST be one of the data types defined in section 7. If the Return is not found or does not contain a value, the client SHOULD assume the 0 data type (Null) and discard the response body.
return = "Return" ":" DIGIT CRLF
12.2. Exception Header
The value of the Exception header specifies an exception thrown by the action and defined in the XHTTP schema of the service. An exception can only be thrown if the client successfully specifies an existing service and action. An exception is composed of a message and a code.
When an exception is thrown, a 550 Exception status MUST be returned by the server. The client SHOULD only search for an Exception header if the server returns the status code 550. If the Exception header is not found or does not contain a value, the client SHOULD assume the string Unknown exception as the message and the integer 108 as the code. If the Exception header does not specify a code, the client SHOULD assume 0. The response MUST NOT contain more than 1 exception. When an exception is thrown by an action, the server MUST discontinue performing the action and proceed to process the response.
exception = "Exception" ":" TEXT [ ";" DIGIT ] CRLF
13. References
- R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach and T. Berners-Lee, Hypertext Transfer Protocol - HTTP/1.1, RFC 2616, June 1999
- Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, François Yergeau, Extensible Markup Language (XML) 1.0 (Fifth Edition), W3C Recommendation, November 2008
- Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, SOAP Version 1.2 Part 1: Messaging Framework (Second Edition), W3C Recommendation, April 2007
- Erik Christensen, Francisco Curbera, Greg Meredith, Sanjiva Weerawarana, Web Services Description Language (WSDL) 1.1, W3C Note, March 2001
- Luc Clement, Andrew Hately, Claus von Riegen, Tony Rogers, Universal Description Discovery and Integration (UDDI) Version 3.0.2, UDDI Spec Technical Committee Draft, 2004
- C. Matthew MacKenzie, Ken Laskey, Francis McCabe, Peter F Brown, Rebekah Metz, OASIS Reference Model for Service Oriented Architecture (SOA) 1.0, OASIS Standard, October 2006
- Dave Winer, XML-RPC, Specification, June 1999
- D. Crockford, JavaScript Object Notation (JSON), RFC 4627, July 2006
- Bradner S, Keywords for use in RFCs to Indicate Requirement Levels, BCP 14, RFC 2119, March 1997
- Crocker D, Standard for The Format of ARPA Internet Text Messages, STD 11, RFC 822, August 1982
- US-ASCII. Coded Character Set - 7-Bit American Standard Code for Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986
- ISO-8859. International Standard -- Information Processing -- 8-bit Single-Byte Coded Graphic Character Sets -- Part 1: Latin alphabet No. 1, ISO-8859-1:1987. Part 2: Latin alphabet No. 2, ISO-8859-2, 1987. Part 3: Latin alphabet No. 3, ISO-8859-3, 1988. Part 4: Latin alphabet No. 4, ISO-8859-4, 1988. Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988. Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987. Part 7: Latin/Greek alphabet, ISO-8859-7, 1987. Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988. Part 9: Latin alphabet No. 5, ISO-8859-9, 1990
- Moore K, MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text, RFC 2047, November 1996
- David C. Fallside, Priscilla Walmsley, XML Schema Part 0: Primer Second Edition, W3C Recommendation, October 2004
- Philip Hazel, Perl-Compatible Regular Expression Library, September 2011
- ISO-8601. International Standard -- Data elements and interchange formats -- Information interchange -- Representation of dates and times, 2004
14. Acknowledgments
It is worth mentioning that XHTTP was developed and tested using open source software, namely Linux (Ubuntu), gedit and Mozilla Firefox with the Firebug extension.
15. Changes
- Current version reflects no changes
