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:
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 Note: 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 |
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).
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.
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.
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.
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.
This section covers the following topics:
In order to pass a user ID and password to Tamino, the following methods are available:
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.
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.
Tamino supports the following types of authentication for client requests:
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).
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.
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.
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.
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.
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.
