This introduction summarizes the methods available for programming against the X-Machine using HTTP requests.

The information in this introduction is organized under the following headings:

Accessing Documents in the X-Machine

Tamino's X-Machine can store and retrieve XML documents as well as non-XML documents. In X-Machine terms, XML documents are well-formed XML documents.

X-Machine provides two methods of accessing documents:

  • Using plain URL addressing: Individual documents can be addressed using a URL in an HTTP GET, PUT, DELETE or HEAD request. The URL reflects a certain directory path structure that addresses the document uniquely. If you want to access a non-XML document in Tamino, you must use this method. With plain URL addressing, X-Machine behaves like an HTTP server, meaning that the response is returned only via HTTP mechanisms and HTTP-related return codes. If a document is requested using the GET method, it is returned in the HTTP response body.

    This access method is described in the section Requests using Plain URL Addressing.

  • Using X-Machine commands: This access method allows special commands to be sent to the X-Machine either in URLs that are sent using the HTTP GET method or as HTML form data that is sent using the HTTP POST method.

    If the GET method is used, the commands are provided in the URL as keyword/value pairs in the search part of the URL (as defined in section 3.3, HTTP of the IETF document RFC1738, The URL path is separated from the commands by a question mark ("?"). If there are two or more commands in a single URL, they are separated by an ampersand character ("&").

    This access method is described in the section Requests using X-Machine Commands.

    X-Machine commands support all of the X-Machine functionality provided by plain URL addressing and support a wide range of additional operations. The X-Machine responds to each request with an appropriate X-Machine response document inside the HTTP response body rather than returning a plain HTTP response. If, for example, an application requests a set of documents to be returned from the X-Machine, the returned documents are enclosed by default in the HTTP response body inside an XML wrapper. This wrapper consists of elements and attributes defined in the Tamino namespace using the prefix "ino", such as Tamino return codes and cursor information. The wrapper can be suppressed; see the section Suppressing the Tamino Response Wrapper for further information.

Storage and Retrieval Format of XML and non-XML Documents

When storing and retrieving documents, the following rules apply:

  • The X-Machine converts XML documents to Unicode before storing them in Tamino.

  • By default, the X-Machine converts non-XML text documents to Unicode before storing them in Tamino. However, there is an option to suppress this conversion, i.e. to store and retrieve the documents unconverted. This option is activated by specifying the element tsd:noConversion as a child of the element tsd:nonXML in the schema for the non-XML doctype. See the description of the element tsd:nonXML in the Schema Reference Guide for more information.

    When tsd:noConversion is specified, documents are processed as follows:

    • When a document is stored the character encoding which was given in the HTTP request in the Content-Type field is stored.

    • Indexing can be performed on a non-XML document only if the character coding is given in the HTTP header.

    • When a document is retrieved, the data is returned without any conversion being performed. This applies even if the Accept-Charset HTTP header field is set. If a character encoding was specified in the HTTP header when the data was stored, this character encoding is returned in the header of the HTTP response.

  • Binary documents are stored and retrieved unchanged byte for byte in Tamino.

See the section Media Type Requirements for a description of how Tamino distinguishes between XML and non-XML documents.


Security for Tamino databases can be implemented using Tamino's built-in security mechanism that is based on entries in a special collection called ino:security. This is described in detail in the Security section of the documentation for Tamino Manager.

In addition, some limited security mechanisms are offered by the web server if a web server is used as the interface to Tamino. By configuring the web server, protection is possible at the database level. This controls access to databases, using the same mechanism as for ordinary directory structures under the control of the web server.

Note however that security mechanisms based on the web server are limited in use. It is for example not possible to set security at the collection level because XQuery can be used to access data across collection boundaries.

The Special Collection ino:etc

If a request is made to store an XML or non-XML document, but the request contains no collection name, the document will be stored in the collection ino:etc. In such cases, XML documents and non-XML documents consisting of text are stored with text retrieval indexing applied to the whole document, and non-XML documents (regardless of whether they consist of text or not) are stored in the special doctype ino:nonXML within ino:etc.

The collection ino:etc is always present in every defined database.