Goals

The guiding goals for the RESTXQ specification are:

Interoperability

Only features that are already present in XQuery MUST be applied to create RESTXQ. Any XQuery code that makes use of RESTXQ instead of vendor extensions, is valid XQuery code, and therefore portable. Note that RESTXQ support is required in the XQuery processor to execute resource functions in a Web context.

Simplicity for XQuery developers

XQuery developers MUST NOT have to maintain external or complex code for wiring RESTful services to XQuery functions. Developers should just write standard XQuery.

Vendor Agnostic

RESTXQ MUST NOT assume anything about an implementation above what is defined in XQuery. RESTXQ MUST be equally implementable by any vendor.

Technical improvement

RESTXQ MUST improve on the current approaches, a comprehensive review was undertaken here.

Audience

This specification is intended for both vendors and developers looking to implement RESTXQ in their products, XQuery developers looking to use the RESTXQ features defined in this specification, and individuals wishing to establish the correctness of implementations with respect to the requirements of this specification.

This document assumes that readers already have at least a basic understanding of XQuery, and an understanding of Web technologies and server side scripting.

Namespaces and Prefixes

The annotations and functions discussed in this document are contained in namespaces (see [[XML-NAMES]]) and referenced using an xs:QName:

• http://exquery.org/ns/restxq, associated with rest.
• http://www.w3.org/2010/xslt-xquery-serialization, associated with output.
• http://expath.org/ns/http-client, associated with http.
• http://exquery.org/ns/restxq/error, associated with rerr.

The namespace prefix used for the functions, datatypes and errors can vary, as long as the prefix is bound to the correct URI.

Background

RESTXQ is heavily influenced by [[?JAX-RS]]. However, we simplify and deviate from JAX-RS predominantly due to the language structure differences between Java and XQuery. Where JAX-RS describes Resource Classes and Resources Methods for Java, in XQuery we simply use the term Resource Function; for mapping HTTP calls to XQuery invocation, our unit of granularity is the XQuery function.

Through the use of annotations on functions in XQuery, we declaratively mark-up the HTTP capabilities of a function. To minimise refactoring by developers when adding annotations to existing code, two measures must be respected by implementations:

1. Implementations of RESTXQ MUST support annotated functions which have additional function parameters which are not annotation mapped, providing the cardinality type of those un-mapped parameters accepts an empty sequence.
2. Implementors MUST not enforce the order of function parameters. Whether mapped by annotations or not is unimportant, as annotations explicitly name the parameters to which they are mapped.

Templates

Some of the RESTXQ Annotations make use of Templates, which allow for the substitution of parameters from the request into the query. The syntax of these templates is very simple and is designed to be familiar to existing XQuery developers, it is expressed in .

The Template appears inside a string literal within the annotation, but the meaning is that the value of the templated substitution MUST be used as the parameter to the named argument of the annotated function.

          {$number-of-cats}
        

In the example above, a parameter given from the template substitution MUST be set for the function argument called 'number-of-cats' on the annotated function.

Resource Function Constraints

Constraints restrict the service requests that a Resource Function MAY process.

            declare
              %rest:path("/stock/widget/{$id}")
            function local:widget($id as xs:int) {
              fn:collection("/db/widgets")//widget[@id eq $id]
            };
          

            declare
              %rest:DELETE
              %rest:path("/widget/{$id}")
            function local:widget($id as xs:int) {
              delete node fn:collection("/db/widgets")//widget[@id eq $id]
            };
          

            (: Will only be invoked if a user supplies one of the specified media types :)
            declare
              %rest:path("/widgets")
              %rest:consumes("application/xml", "application/atom+xml")
            function local:widgets() {
              fn:collection("/db/widgets")/widgets
            };
          

            (: Will only be invoked if a user accepts one of the specified media types :)
            declare
              %rest:path("/widgets")
              %rest:produces("application/xml")
            function local:widgets() {
              fn:collection("/db/widgets")/widgets
            };
          

Resource Function Parameters

Parameters to Resource Functions are extracted from the RESTful Web Service request and passed in as additional function parameters. Unlike constraints, parameters are always optional. Resource Function Parameters use the template syntax to map the request parameter onto a function parameter. They may also provide a default value should the parameter not be present in the request. Resource Function Parameters always place the following constraints on the function parameters that they map to:

1. The cardinality MUST allow for zero or many atomic values in the case of Query, Form or Header parameters, or zero or one atomic value in the case of Cookie parameters, otherwise an error MUST be raised by the implementation.
2. The type MUST inherit from xs:anyAtomicType, otherwise, an error MUST be raised by the implementation.

Conversion from the parameter string to the required function parameter type is performed at run-time, and an error is raised if conversion is impossible.

The annotations in this section MUST have two or more arguments:

1. The first argument represents the name of a parameter expected in the request.
2. The second argument contains a reference to the Resource Function Parameter.
3. The remaining arguments form the default value, which is assigned if the expected parameter is not present in the request.

            declare
              %rest:GET
              %rest:path("/widget/{$id}")
              %rest:query-param("client", "{$client}", "unknown")
            function local:widget($id as xs:int, $client as xs:string*) {
              fn:collection("/db/widgets")//widget[@id eq $id][@client = $client]
            };
          

            declare
              %rest:GET
              %rest:path("/widget/{$id}")
              %rest:form-param("client", "{$client}", "unknown")
            function local:widget($id as xs:int, $client as xs:string*) {
              fn:collection("/db/widgets")//widget[@id eq $id][@client = $client]
            };
          

            declare
              %rest:GET
              %rest:path("/widget/{$id}")
              %rest:header-param("X-Client-Type", "{$client-type}")
            function local:widget($id as xs:int, $client-type as xs:string*) {
              fn:collection("/db/widgets")//widget[@id eq $id][@client-type = $client-type]
            };
          

            declare
              %rest:GET
              %rest:path("/widget/{$id}")
              %rest:cookie-param("tasty_cookie, "{$tastycookie}")
            function local:widget($id as xs:int, $tastycookie as xs:string*) {
              fn:collection("/db/widgets")//widget[@id eq $id][@flavor = $tastycookie]
            };
          

Serialization

The results of a Resource Function may be serialized back to an HTTP response for the RESTful web service response. A Resource Function may return one of three response types:

1. A Resource, i.e. just content.
2. HTTP headers, for example acknowledging the request or providing a status code or additional information.
3. Both HTTP Headers and a Resource

1. If the function is from within a Main Module, and if an output declaration exists, then we use this as the default serialization settings for each Resource Function in that module.
2. Output Declarations may be re-written as annotations on any Resource Function, e.g. %output:method("xml"). These annotation output declarations override any defaults from 1.
3. If no Output Declaration, annotated or otherwise, is provided, then the default is to serialize as XML, UTF-8 encoding, with indenting.

1. For a function that returns just a resource, either:
   1. If the result type is omitted from the function, it is assumed to be document-node(element()) or just element(), and XML Serialization should be applied to the result of the function. The annotation %output:method, if present, MUST be set to xml. This is known as the Default Resource Response rule.
   2. If the result type is present, it MUST be a type which is compatible with the chosen serialization method, defined by either the XQuery output declaration or overridden by the %output:method annotation on the Resource Function. The default serialization method is XML. If the result type is not compatible with the serialization, an implementation MUST throw an error. This is known as the Typed Resource Response rule.
2. For a function that returns just HTTP headers, the result type of the function MUST be defined as document-node(element(rest:response)). Any other annotations that effect the serialization of the result are ignored.
3. For a function that returns both HTTP headers and a resource, the result type of the function MUST be defined as item()+. The first item in the result sequence is the HTTP headers i.e. document-node(element(rest:response), the second item in the result sequence is the resource itself; Subsequently both the Default Resource Response rule and the Typed Resource Response rule MUST be applied to the result sequence.

Response Format

A REST Response document may be returned from a function either with or without a Resource. The purpose of this document is to control the REST (in this case HTTP) response sent back to the client of the RESTful web service.

<rest:response>
  (http:response?)
</rest:response>

<http:response status?="integer" message?="string">
  (http:header*)
</http:response>

<http:header name="string" value="string"/>

Should the status be omitted for the response, or should a REST Response document not be returned from a Resource Function, then the status defaults to 200 OK. It is expected that implementations will make use of sane defaults for HTTP headers as part of their HTTP responses, however any default headers MUST be overridable by the values set in the REST Response document.

As an example, the following response can be returned to trigger a client-side redirection:

<rest:response>
  <http:response status="302" message="Temporary Redirect">
    <http:header name="location" value="/new/location"/>
  </http:response>
</rest:response>

Base URI

The base URI of a Resource Function is implementation-defined. That is to say that an implementation is free to define either statically or dynamically the URI part that appears before the relative URI of any Path Annotation ().

Content Negotiation

Support for content negotiation ([[RFC7231]]) of formats is indirectly provided by the %rest:consumes and %rest:produces annotations.

            (: Combining consumes and produces provides content negotation support :)
            declare
              %rest:path("/widgets")
              %rest:consumes("application/xml", "application/atom+xml")
              %rest:produces("application/xml", "application/json")
            function local:widgets() {
              fn:collection("/db/widgets")/widgets
            };
          

HTTP Request Matching

In many cases, there is more than one Resource Function that could service an incoming HTTP Request. This chapter defines how the best matching Resource Function is selected. The specificity of a Resource Function is governed by the following rules, which MUST be applied in order.

The following Resource Function:

declare function
  %rest:GET
  %rest:path("/a/b/c")
  %rest:consumes("application/xml")
local:function-1() {
  <fn>1</fn>
};

is more specific than:

declare function
  %rest:GET
  %rest:path("/a/b/c")
local:function-2() {
  <fn>2</fn>
};
          

/person/elisabeth
/person/{$name}
/{$type}/elisabeth
/{$type}/{$name}
/person
/{$type}

Registry Functions

Functions to assist in managing the RESTXQ Registry.

rest:resource-functions() as document-node(element(rest:resource-functions))

<rest:resource-functions>
  rest:resource-function*
</rest:resource-functions>

<rest:resource-function
  xquery-uri = xs:anyURI>
  <rest:identity
    namespace = xs:anyURI
    local-name = xs:NCName
    arity = xs:int/>
</rest:resource-function>

URI Functions

URI functions assist in the construction and selection of URIs.

rest:base-uri() as xs:anyURI

rest:uri() as xs:anyURI

rest:build-absolute-uri($path-segments as xs:anyAtomicType+) as xs:anyURI

Minimal Conformance

An implementation that claims Minimal Conformance to this specification MUST provide all of the following items:

1. An implementation of everything specified in this document.

2. A definition of every item specified to be implementation-defined.