forked from xproc/3.0-steps
/
http-request.xml
204 lines (173 loc) · 9.31 KB
/
http-request.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
<section xmlns="http://docbook.org/ns/docbook"
xmlns:cs="http://www.w3.org/XML/XProc/2006/04/components#"
xmlns:e="http://www.w3.org/1999/XSL/Spec/ElementSyntax"
xmlns:p="http://www.w3.org/ns/xproc"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="c.http-request">
<title>p:http-request</title>
<para>The <code>p:http-request</code> step provides for interaction
with resources over HTTP or related protocols.
The input
document provided on the <port>source</port> port specifies a request
by a single <tag>c:request</tag> element. This element specifies
the method, resource, and other request properties as well as possibly
including an entity body (content) for the request.</para>
<p:declare-step type="p:http-request">
<p:input port="source" content-types="any"/>
<p:output port="result" sequence="true" content-types="any"/>
<p:option name="serialization" as="map(xs:QName,item()*)?"/>
</p:declare-step>
<para>The <option>serialization</option> option is provided to control the
serialization of any content which is sent as part of the request.
The effect of these options is as specified in <biblioref linkend="xproc30"/>.
See <link linkend="c.request_body"/> for a discussion of when serialization
occurs in constructing a request.</para>
<para><error code="C0040">It is a <glossterm>dynamic error</glossterm>
if the document element of the document that arrives on the
<port>source</port> port is not <tag>c:request</tag>.</error></para>
<note xml:id="ednote-json" role="editorial">
<title>Editorial Note</title>
<para>Can the input document be JSON?</para>
</note>
<section xml:id="cv.request">
<title>Specifying a request</title>
<para>An HTTP request is represented by a <tag>c:request</tag> element.</para>
<e:rng-pattern name="VocabHttpRequest"/>
<para><error code="C0006">It is a <glossterm>dynamic error</glossterm> if the
<tag class="attribute">method</tag> is not specified on a <tag>c:request</tag>.
</error>
<error code="C0005">It is a <glossterm>dynamic error</glossterm> if the
request contains a <tag>c:body</tag> or <tag>c:multipart</tag> but the
<tag class="attribute">method</tag> does not allow for an entity body being sent with the request.</error></para>
<para><error code="C0004">It is a <glossterm>dynamic error</glossterm> if the
<code>status-only</code> attribute has the value <literal>true</literal> and
the <code>detailed</code> attribute does not have the value <literal>true</literal>.</error></para>
<para>The <code>method</code> attribute specifies the method to be
used against the IRI specified by the <code>href</code> attribute,
e.g. <code>GET</code> or <code>POST</code> (the value is not case-sensitive).
If the <code>href</code>
attribute is not absolute, it will be resolved against the base URI of
the element on which it is occurs.</para>
<note xml:id="note-http-get">
<para>In the case of simple “GET” requests, implementors are encouraged
to support as many protocols as practical. In particular, pipeline authors may
attempt to use <tag>p:http-request</tag> to load documents with computed
URIs using the <literal>file:</literal> scheme.</para></note>
<para>If the <code>username</code> attribute is specified, the
<code>username</code>, <code>password</code>,
<code>auth-method</code>, and <code>send-authorization</code>
attributes are used to handle authentication according to the selected
authentication method.</para>
<para>For the purposes of avoiding an authentication challenge, if the
<code>send-authorization</code> attribute has the value
<literal>true</literal> and the authentication method specified by the
<code>auth-method</code> supports generation of an
<code>Authorization</code> header without a challenge, then an
<code>Authorization</code> header is generated and sent on the first
request. If the <code>send-authorization</code> attribute is absent or
has the value
<literal>false</literal>, then the first request is sent without an
<code>Authorization</code> header.</para>
<para>If the initial response to the request is an
authentication challenge, the <code>auth-method</code>,
<code>username</code>, <code>password</code> and any relevant data from
the challenge are used to generate an
<code>Authorization</code> header and the request is sent again. If
that authorization fails, the request is not retried.</para>
<para>Appropriate values for the <code>auth-method</code> attribute
are “Basic” or “Digest” but other values are allowed.
If the authentication method is “Basic” or “Digest”, authentication
is handled as per <biblioref linkend="rfc2617"/>.
<impl>The
interpretation of <code>auth-method</code> values on
<tag>c:request</tag> other than “Basic” or “Digest” is
<glossterm>implementation-defined</glossterm>.</impl></para>
<para><error code="C0003">It
is a <glossterm>dynamic error</glossterm> if a <option>username</option>
or <option>password</option> is specified without specifying an
<option>auth-method</option>, if
the requested
<option>auth-method</option> isn't supported, or the authentication
challenge contains an authentication method that isn't
supported.</error> All implementations are required to support "Basic"
and "Digest" authentication per <biblioref linkend="rfc2617"/>.</para>
<para>The attribute <code>timeout</code> controls the time the XProc processor is
waiting for the request to be answered. If a value is given for <code>timeout</code>
it is taken as the number of seconds to wait for the response to be delivered.
If no response is received after that time, the request is terminated.</para>
<itemizedlist>
<listitem>
<para><error code="C0078">It is a <glossterm>dynamic error</glossterm>
if <option>fail-on-timeout</option> is specified as
<literal>true</literal> and a value is given for
<option>timeout</option> and the <tag>p:http-request</tag> is not finished in the
time specified by <option>timeout</option>.</error>
</para>
</listitem>
<listitem>
<para>If <code>fail-on-timeout</code> is <literal>false</literal>, a
<code>c:response</code> document with <code>status=408</code> is
generated.</para>
</listitem>
<listitem>
<para>If no value is given for <code>fail-on-timeout</code>,
<literal>false</literal> is assumed. If no value is given for
<code>timeout</code>, <code>fail-on-timeout</code> is ignored.</para>
</listitem>
</itemizedlist>
<note>
<title>Note</title>
<para>Please note the difference between option <code>p:timeout</code>
on <code>p:http-request</code> and the attribute <code>timeout</code>
in combination with <code>fail-on-timeout="true"</code> on
<code>c:request</code>. If the step does not finish in the set time,
<code>D0053</code> is raised. If the request does not finish in time
and fail-on-timeout is true, <code>C0078</code> is raised. The actual
times after which a timeout is detected may also differ slightly.
</para>
</note>
<para>The <code>c:header</code> element specifies a
header name and value, either for inclusion in a request, or as received in a response.</para>
<e:rng-pattern name="VocabHeader" xml:id="cv.header"/>
<para>The request is formulated from the attribute values on the
<tag>c:request</tag> element and its
<tag>c:header</tag> and <tag>c:multipart</tag> or <tag>c:body</tag> children,
if present, and transmitted to the host (and port, if present) specified by the
<code>href</code> attribute. The details of how the request entity body, if any, is
constructed are given in <xref linkend="c.response_body"/>.</para>
<para>When the request is formulated, the step and/or protocol
implementation may add headers as necessary to either complete the
request or as appropriate for the content specified (e.g. transfer
encodings). A user of this step is guaranteed that their requested
headers and content will be sent with the exception of any conflicts
with protocol-related headers.</para>
<para>The <tag>p:http-request</tag> step allows users to specify
independently values that are not always independent. For example,
some combinations of <tag>c:header</tag> values
(e.g., <literal>Content-Type</literal>)
may be inconsistent
with values that the step and/or protocol implementation must set. In
a few cases, the step provides more than one mechanism to specify what
is actually a single value (e.g., the boundary string in multipart
messages).
<error code="C0020">It is a
<glossterm>dynamic error</glossterm> if the the user specifies a value
or values that are inconsistent with each other or with the requirements
of the step or protocol.</error>
</para>
</section>
<xi:include xmlns:db="http://docbook.org/ns/docbook" href="payloads/request_body.xml"/>
<xi:include xmlns:db="http://docbook.org/ns/docbook" href="payloads/request_response.xml"/>
<xi:include xmlns:db="http://docbook.org/ns/docbook" href="payloads/response_body.xml"/>
<section xml:id="example-http-request">
<title>HTTP Request Example</title>
<para>A simple form might be posted as follows:</para>
<programlisting language="xml"><xi:include href="../../../../build/examples/form.post.txt" parse="text"/></programlisting>
<para>and if the response was an XHTML document, the result document would be:</para>
<programlisting language="xml"><xi:include href="../../../../build/examples/form.response.txt" parse="text"/></programlisting>
</section>
<simplesect>
<title>Document properties</title>
<para feature="http-request-preserves-none">No document properties are preserved.</para>
</simplesect>
</section>