Tamino XML Server Version 9.7
 —  X-Machine Programming  —

Requests using Plain URL Addressing

This section describes the format of the URL used for plain URL addressing, and the corresponding HTTP request and response structure.

Plain URL addressing access is done using the HTTP methods PUT, GET, DELETE, and HEAD.

The methods PUT, DELETE and HEAD do not return an HTTP body. For GET, the HTTP body contains only the required document, i.e. there is no additional XML wrapping.

Plain URL addressing is described further under the following headings:


URL format for Plain URL addressing

An X-Machine document can be addressed directly via HTTP using the following URL structure:

http://HostName:PortNumber/tamino/DatabaseName/CollectionName/DoctypeName/DocumentName

with the following meaning:

HostName

Host address for the web werver.

PortNumber

Port number for the web server.

DatabaseName

Name of the Tamino database.

CollectionName The name of the X-Machine collection that contains the existing document or will contain the new document.
DoctypeName The name of the X-Machine doctype that contains the existing document or will contain the new document.
DocumentName

When storing a document, Tamino assigns this name to the document. The name could be a string such as a file name, e.g. mypicture01.jpg. Use the same name to retrieve the document in subsequent operations. The document name is returned in the pseudo-attribute ino:docname when the document is retrieved via X-Query.

Note:
The document name is unique within a given doctype.

When retrieving a document, it is possible to specify either the name of the required document or the document's ID. The document ID is assigned automatically by Tamino when the document is originally stored, and the ID value is returned in the pseudo-attribute ino:id when the document is retrieved via X-Query. If the document ID is used instead of the document name, it must be prefixed by "@".

Since the names HostName, PortNumber, DatabaseName, CollectionName, DoctypeName and DocumentName are used in a URL as shown above, any characters in their names that are not allowed in a URL must be URL-encoded. For example, the characters "#", "?", "&" and "=" have a special meaning in URLs, so if a document name contains any of these characters (specified by the ino:docname attribute), it is necessary to use the escaped versions of these characters when addressing the document in a URL (namely "%23" for "#", "%3F" for "?", "%26" for "&" and "%3D" for "=").

This form of addressing may be used for XML and non-XML documents.

Even though individual documents are accessible via plain URL addressing, the collections and doctypes used to store the documents must be created not by plain HTTP requests but by the X-Machine command _define.

The explicit creation of a doctype by passing a schema document in a _define command is not required (or in some cases prohibited) if the corresponding collection has been configured for schemaless storage (for example, the collection ino:etc).

Top of page

Addressing Existing Documents via Document ID

When addressing an existing X-Machine document, the related URL may contain the document's ID instead of the document's name (as specified by ino:docname). This reference is indicated using an "at" ("@") character.

For example, the following URL specifies the Tamino document with document ID 4711635 in the collection "FDSdemo_e" and doctype "Construction", in the database "MyTestDb01", where the web server is at port "80" of the machine "myhost":

http://myhost:80/tamino/MyTestDb01/FDSdemo_e/Construction/@4711635

When a new document is stored, the X-Machine assigns an document ID automatically to the document. The document ID is returned as the value of the ino:id attribute in the ino:object element in the Tamino response document.

It is not possible for a client to assign an explicit ID when a new document is being stored. A 31-bit integer is used to represent the document ID, so the total number of document IDs per doctype is approximately 2,000,000,000. A document ID is unique within a given doctype, but does not need to be unique across doctypes, i.e. a document ID in one doctype can be the same as a document ID in another doctype. In the Tamino namespace, the name ino:id is reserved for the document ID.

Note:
When a document is deleted, the document ID can be reused when a new document is created. This behaviour is controlled by the schema element tsd:systemGeneratedIdentity.

Top of page

Criteria for Inserting or Replacing a Document

When a document is sent to Tamino, Tamino uses the values of the document ID and/or document name that can optionally be supplied in the input request to decide whether to insert a new document or replace an existing document.

The document ID of an existing document can either be supplied in the URL (as described above) or as the value of the ino:id attribute of the document's root element (if the document is an XML document), or both. If both are supplied, the values must be identical, otherwise an error will be returned.

The document name of an existing document can only be supplied in the URL.

If a document name and a document ID are both supplied, a document with this name and ID must already exist, otherwise an error will be returned.

The rules determining whether a new document will be inserted or an existing document will be replaced are the same as for the X-Machine _process command. See the section Criteria for inserting or replacing a document within the description of the _process command for details.

If you supply neither a document name nor a document ID when using plain URL addressing as described here, an error will be returned. Note however that the _process command allows you to omit both the document name and the document ID when inserting a new document. See the _process command for details.

Top of page

HTTP Header and Body Content

When issuing HTTP GET, DELETE and HEAD requests to Tamino, no HTTP body is supplied. For an HTTP PUT request, the body must contain the document (XML or non-XML). For XML documents, wrapping is neither required nor allowed.

The URL describes the location for the document inside Tamino.

After a successful response from Tamino, the HTTP body will contain data if a GET was issued. This data is the requested document without any XML wrapping. The HTTP header will contain standard HTTP status codes.

If a PUT was issued, the HTTP response header field X-INO-id will contain the document ID of the document that was processed.

If a PUT, GET or DELETE was issued, the HTTP response header field X-INO-Docname will contain the name of the document that was processed.

The version number of the Tamino server being used is returned in the HTTP response header for every HTTP request. The value is returned in the field X-INO-Version.

Top of page

HTTP Status Codes

The following table lists a selection of the standard HTTP status codes that can result from a plain URL addressing request to the X-Machine. For the full list of HTTP status codes, see the HTTP specification at http://www.ietf.org/rfc/rfc2616.txt.

HTTP status code HTTP Method Meaning
200 GET OK, document retrieved
200 HEAD OK, document found
201 PUT OK, document created (did not already exist)
204 DELETE OK, document deleted
204 PUT OK, existing document replaced
400

GET, DELETE, HEAD, PUT

Request cannot be processed (e.g. unknown ino:id value or document not well formed)
401 GET, DELETE, HEAD, PUT

Access denied (the specified user ID and/or password are not valid)

404 GET, DELETE, HEAD Document not found
500 GET, DELETE, HEAD, PUT

Internal error in the Tamino server, document not processed (i.e. not retrieved, not deleted, not stored)

502 GET, DELETE, HEAD, PUT

Error in a communications component such as a web server interface

503 GET, DELETE, HEAD, PUT

Service unavailable temporarily (e.g. due to a locking conflict)

When accessing WebDAV resources, various other response codes are possible. Please refer to RFC2518, RFC3253, RFC3744 and the WebDAV SEARCH specification at http://www.ietf.org/ for a complete list.

Top of page

Authentication Aspects

This section covers the following topics:

Passing a user ID and password to Tamino

In order to pass a user ID and password to Tamino, the following methods are available:

Basic authentication field in HTTP header

Using the standard mechanism for the basic authentication scheme of the HTTP protocol, a user ID and password can be passed to Tamino. The field Authorization of the HTTP header can be used for this purpose.

Note:
The field X-INO-Authorization, if present in the HTTP header, takes precedence over the field Authorization. See the section Special Tamino authentication field in HTTP header for details.

The format of the field Authorization is as follows:

Authorization: Basic ID:Password

where ID:Password is the user ID and password in UTF-8 encoding separated by a colon, then converted to base64 representation. For a description of base64 encoding, which defines a mapping of any binary data to printable characters in 7-Bit US-ASCII, see http://www.ietf.org/rfc/rfc2045.txt.

When using a user domain, the user ID should be preceded by the domain name and a backslash, for example, "MyDomain\MyUserID". Note that Tamino domains and user IDs are case-sensitive, also when they are mapped to a Windows domain.

Special Tamino authentication field in HTTP header

The Tamino-specific field X-INO-Authorization can be used in the HTTP header to pass a user ID and password.

Note:
When the fields Authorization and X-INO-Authorization are both present in the HTTP header, the field X-INO-Authorization takes precedence over the field Authorization.

The format of the field X-INO-Authorization is as follows:

X-INO-Authorization: Basic ID:Password

where ID:Password is the user ID and password in UTF-8 encoding separated by a colon, then converted to base64 representation. For a description of base64 encoding, which defines a mapping of any binary data to printable characters in 7-Bit US-ASCII, see http://www.ietf.org/rfc/rfc2045.txt.

When using a user domain, the user ID should be preceded by the domain name and a backslash, for example, "MyDomain\MyUserID". Note that Tamino domains and user IDs are case-sensitive, also when they are mapped to a Windows domain.

Authentication for client requests

Tamino supports the following types of authentication for client requests:

Non-authenticated access

This method can be used when the Tamino XML property Authentication is set to "none". In this case, the user ID found in the header fields will be used and the password will be ignored. This is not recommended if access restrictions are defined using Tamino Security (see the section Tamino Security in the documentation of the Tamino Manager for information).

Authentication using web server authentication

This method can be used when the Tamino XML property Authentication is set to "web server". The user ID and password, which must be known to the authenticating web server, must be provided in the HTTP basic authentication header field.

If the property is set to "web server" and a non-authenticating web server is used, no user ID will be passed to Tamino, so all requests will be treated as if they originate from the default user group; here, only the basic authentication scheme is supported.

For this type of authentication to work, the web server must be configured to use basic authentication and must be able to authenticate the users who will communicate with Tamino using this method. Please refer to the documentation of your web server for information on how to do this configuration.

Tamino authentication

This method can be used when the Tamino XML property Authentication is set to "tamino". The user ID and password can be passed in either the HTTP basic authentication header field or the special Tamino authentication header field. Tamino authenticates the user against the users known to Tamino (users stored directly in Tamino or users known to Tamino via an LDAP server or the local operating system). If the authentication fails, an HTTP response 401 is returned.

Top of page

Transaction Aspects

In the same way as for X-Machine commands, requests using plain URL addressing can be executed in the context of a transaction that is part of an X-Machine session established via the _connect command. As there is no way to pass request parameters using plain URL addressing, the values of various session parameters can be passed in HTTP request header fields.

Setting session ID and session key

The values of _sessionid and _sessionkey can be passed in the HTTP request header fields X-INO-Sessionid and X-INO-Sessionkey. For details of session ID and session key see the topic Transaction-Related Commands.

Overriding session parameters

It is possible to override certain session parameter defaults (typically set on the X-Machine _connect command) in an HTTP request by supplying values for the following HTTP request header fields:

HTTP request header field Corresponding X-Machine parameter
X-INO-isolation _ISOLATION
X-INO-isolationLevel _ISOLATIONLEVEL
X-INO-lockMode _LOCKMODE
X-INO-lockWait _LOCKWAIT

When the request completes, the values of the session parameters revert to the default values.

For more information on these parameters, refer to the section Session Parameters.

Top of page