As a consequence of a recent question in the #4suite channel about support for remote web services (in the general sense) and a recent reoccuring need to refer to scattered notes, mailing list threads, and such, this is my attempt to document the HTTP behavior of the repository (emphasizing those that are RESTful).
Authentication
Servers (unique per port and repository instance) can request mandatory HTTP Authentication. In which case all requests without an HTTP Authorization header (or an undecipherable one) will result in a 401 reponse.
Upon authentication failure (for servers that request mandatory authentication), a 401 response is sent back indicating the given user failed authentication.
For all others, a 403 request is sent back.
Interpreting Request URIs
The 4Suite Repository HTTP Server interprets Request URIs as:
- Repository Paths
- XSLT Invokations
- URI Patterns
Repository Paths
Repository Paths are direct references to repository resources.
GET Requests
The resources are returned as is with the 'Content-type' header set to their Internet Media Type. The 'Last-Modified' header is populated with the date of last modification (as given by the repository) in order to help remote clients cache resource references.
If the resource doesn't exist, a 404 response is returned.
PUT Requests
If the path refers to an existing resource, it's content is updated with the body of the request. Otherwise, a new resource is created using the body of the request as the content and the Content-type header as the Internet Media Type.
The RFC semantics of this verb don't map so cleanly where the resource does not exist. The server is bound (by RFC2616) to attempt to interpret all Content-* headers. So, other than Content-length, all other such headers result in a 501 response (not supported).
Any XML-related content-type entries (?:text|application)/.*\+?xml to be REGEX-specific) will cause an XML document to be created. These have 'special' behavior in the repository and invokes some additional introspection of the content (the document could be a user, group, RDF document, an XML->RDF mapping, etc..).
Otherwise, an attempt to parse the body of the request (via 4Suite XML's Domlette) is made. If successful, then the repository assumes an XML document is being created (and the same additional introspection occurs).
If the new resource is created successfully, a 201 response is sent.
DELETE Requests
The resource identified by the path is deleted from the repository. Upon failure, the appropriate reponse code is sent: 404, 401, 500
POST Requests
POST requests only have meaning in the contenxt of XSLT invokations, in which case the request body is considered the source document for the XSLT transformation.
XSLT Invokation
I can't speak with ful authority on the subject, but from my sufficient (so far) understanding (which is limited to the use of XSLT as a server-side mechanism for HTML form and XForms submission processing) the default mechanism for triggering XSLT invokations is:
Request URI-based Invokation
The path portion of the URI is interpreted as the repository path of the source document. The 'xslt' parameter is the repository path of the XSLT document to use for the transformation. The remaining parameters are interpreted as name/value pairs of top-level XSLT parameters to pass on to the XSLT processor.
POST-based Invokation
The interpretation is the same except that all the request arguments (as submitted from an HTML form, for instance) except 'xslt' are interpretated as name/value pairs of top-level XSLT parameters as well.
Older Akara Entries on the subject
- Handling Web forms with XSLT scripts in the repository
- Built-in parameters for XSLT processing invoked from the repository
- The architecture of 4Suite Web applications
URI Patterns as RESTful Services
This is a more recent development, but portions of the server document include Server rules. The original excerpt / references on these can be found here but in summary each server can register the combination of certain URI patterns (as given by a REGEX expression) and request methods (GET,PUT,and/or POST) with XSLT invocations. This includes full control over the parameters and source document (using the original request URI).
Somewhat related
FTSS URI Scheme