REST and XForms Submission
- 1. Introduction
- 2. Inputs and Outputs
- 3. Processing Model
- 4. GET Example
- 5. POST Example
- 6. PUT Example
- 7. DELETE Example
- 8. Handling Errors
- 9. Handling Authentication
1. Introduction
More and more services are exposed and consumed through REST APIs, in other words APIs that leverage
HTTP. In particular, XForms' <xforms:submission>
supports
REST as of XForms 1.1. The XForms Submission processor exposes the functionality of
<xforms:submission>
to XML pipelines and allows you to call REST services from XPL
without creating XForms pages.
2. Inputs and Outputs
Type | Name | Purpose | Mandatory |
---|---|---|---|
Input |
submission
|
Configures the XForms submission | Yes |
Input |
request
|
Refers to the document to submit | Yes |
Output |
response
|
Produces the result document if any | Yes |
The XForms Submission processor is typically called this way from XPL pipelines:
3. Processing Model
The submission
input follows the semantic of <xforms:submission>
, with the
difference that the replace
attribute defaults to the value instance
.
Processing follows the following steps:
-
The document provided on the
request
input is set as the default XForms instance. -
The submission is executed. By default, the submission serializes the default instance, that is the document provided on the
request
input. -
The resulting default instance is produced on the
response
output. In case of sucessful instance replacement, this means that the document resulting from the submission is produced.
If an XForms submission error occurs during the processing of the submission, the response document will be identical to the request document unless you modify it using XForms events and actions.
You have to consume the response
output in order for the submission to be performed, even
if you do not wish to handle the response document.
4. GET Example
This is how you perform a GET of an XML document to the URL http://example.org/list?first=12&size=100
:
5. POST Example
This is how you perform a POST of an XML document to the URL
http://example.org/rest/my-collection
and retrieve an XML response:
6. PUT Example
This is how you perform a PUT of an XML document to the URL
http://example.org/rest/my-collection/my-document
and retrieve an XML response:
7. DELETE Example
This is how you perform a DELETE of a resource located at
http://example.org/rest/my-collection/my-resource
:
In this case the response is read but discarded by using the Null Serializer.
8. Handling Errors
You can handle errors using XML events and actions, including xforms-submit-error
and
xforms:setvalue
.
The above example assumes that the request document contains a <submission-error>
element under its root element, for example:
You can then check that an error occurred by testing that the response document satisfies
/request/submission-error = 'true'
.
9. Handling Authentication
You can use Basic HTTP authentication (the most widely used authentication mechanism over HTTP) in two different ways:
-
With username and password encoded in the URL, for example:
<p:processor name="oxf:xforms-submission"><p:input name="submission"><xforms:submission method="get" action="http://john:password@example.org/list" separator="&"/></p:input><p:input name="request" href="#request"/><p:output name="response" id="response"/></p:processor>This method has the obvious drawback of making authorization credentials visible on the URL. In particular, if that URL may show in logs, error messages, etc.
-
With two extension attributes,
xxforms:username
andxxforms:password
:<p:processor name="oxf:xforms-submission"><p:input name="submission"><xforms:submission method="get" action="http://example.org/list" separator="&" xxforms:username="john" xxforms:password="password"/></p:input><p:input name="request" href="#request"/><p:output name="response" id="response"/></p:processor>