Changes

Jump to navigation Jump to search
735 bytes added ,  16:57, 4 August 2022
no edit summary
If <code><http:header name="Accept-Encoding" value="gzip"/></code> is specified and if the addressed web server provides support for the {{Code|gzip}} compression algorithm, the response will automatically be decompressed.
 
{{Announce|Updated with Version 10:}} The Implementation of the module is now based on the new [https://openjdk.org/groups/net/httpclient/intro.html Java HTTP Client], which provides a better overall performance, uses internal connection pools and follows redirects across different protocols (http, https).
=Conventions=
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|http:send-request|$request as element(http:request)|item()+}}<br />{{Func|http:send-request|$request as element(http:request)?, $href as xs:string?|item()+}}<br />{{Func|http:send-request|$request as element(http:request)?, $href as xs:string?, $bodies as item()*|item()+}}<br/>
|-valign="top"
| '''Summary'''
|Sends an HTTP request and interprets the corresponding response:
* While the contents of the request can be supplied as child of the {{Code|http:body}} element, it is faster and safer to pass them on via the third argument.
* For further information, please check out the [http://expath.org/spec/http-client EXPath] specification.
|-valign="top"
|'''Errors'''
|{{Error|HC0001|#Errors}} an HTTP error occurred.<br/>{{Error|HC0002|#Errors}} error parsing the entity content as XML or HTML.<br/>{{Error|HC0003|#Errors}} with a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.<br/>{{Error|HC0004|#Errors}} the src attribute on the body element is mutually exclusive with all other attribute (except the media-type).<br/>{{Error|HC0005|#Errors}} the request element is not valid.<br/>{{Error|HC0006|#Errors}} a timeout occurred waiting for the response.
'''Query:'''
<pre classsyntaxhighlight lang="brush:xquery">http:send-request(<http:request method='get' status-only='true'/>, 'http://basex.org')</presyntaxhighlight>
'''Result:'''
<pre classsyntaxhighlight lang="brush:xml"><http:response status="200" message="OK">
<http:header name="Date" value="Mon, 14 Mar 2011 20:55:53 GMT"/>
<http:header name="Content-Length" value="12671"/>
<http:header name="Cache-Control" value="max-age=90"/>
<http:body media-type="text/html; charset=utf-8"/>
</http:response></presyntaxhighlight>
==Google Homepage==
'''Query:'''
<pre classsyntaxhighlight lang="brush:xquery">http:send-request(<http:request method='get' href='http://www.google.com' timeout='10'/>)</presyntaxhighlight>
'''Result:'''
<pre classsyntaxhighlight lang="brush:xml">
<http:response status="200" message="OK">
<http:header name="Date" value="Mon, 14 Mar 2011 22:03:25 GMT"/>
</body>
</html>
</presyntaxhighlight>
The response content type can also be overwritten in order to retrieve HTML pages and other textual data as plain string (using {{Code|text/plain}}) or in its binary representation (using {{Code|application/octet-stream}}). With the {{Code|http:header}} element, a custom user agent can be set. See the following example:
'''Query:'''
<pre classsyntaxhighlight lang="brush:xquery">
let $binary := http:send-request(
<http:request method='get'
'Conversion to XML failed: ' || $err:description
}
</presyntaxhighlight>
===SVG Data===
'''Query:'''
<pre classsyntaxhighlight lang="brush:xquery">http:send-request(<http:request method='get'/>, 'http://upload.wikimedia.org/wikipedia/commons/6/6b/Bitmap_VS_SVG.svg')</presyntaxhighlight>
'''Result:'''
<pre classsyntaxhighlight lang="brush:xml"><http:response status="200" message="OK">
<http:header name="ETag" value="W/&quot;11b6d-4ba15ed4&quot;"/>
<http:header name="Age" value="9260"/>
</linearGradient>
...
</svg></presyntaxhighlight>
==POST Request==
'''Query:'''
<pre classsyntaxhighlight lang="brush:xquery">
http:send-request(
<http:request method='post' username='admin' password='admin'>
<http:body media-type='application/xml'/>
</http:request>,
'http://localhost:89848080/rest',
<query>
<text>
</query>
)
</presyntaxhighlight>
'''Result:'''
<pre classsyntaxhighlight lang="brush:xml">
<http:response xmlns:http="http://expath.org/ns/http-client" status="200" message="OK">
<http:header name="Content-Length" value="135"/>
<div>Section 3</div>
</html>
</presyntaxhighlight>
==File Upload==
'''Query:'''
<pre classsyntaxhighlight lang="brush:xquery">
let $path := 'file-to-be.uploaded'
return http:send-request(
</http:multipart>
</http:request>,
'http://localhost:89848080/write-to-temp',
file:read-binary($path)
)
</presyntaxhighlight>
'''RESTXQ service:'''
<pre classsyntaxhighlight lang="brush:xquery">
declare
%rest:POST
});
};
</presyntaxhighlight>
=Errors=
! width="110"|Code
|Description
|-valign="top"
|{{Code|HC0001}}
|An HTTP error occurred.
|-valign="top"
|{{Code|HC0002}}
|Error parsing the entity content as XML or HTML.
|-valign="top"
|{{Code|HC0003}}
|With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.
|-valign="top"
|{{Code|HC0004}}
|The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).
|-valign="top"
|{{Code|HC0005}}
|The request element is not valid.
|-valign="top"
|{{Code|HC0006}}
|A timeout occurred waiting for the response.
=Changelog=
 
;Version 10.0
* Updated: Implementation based on the new [https://openjdk.org/groups/net/httpclient/intro.html Java HTTP Client].
;Version 9.0
;Version 7.6
* Updated: [[#http:send-request{{Function||http:send-request]]}}: {{Code|HC0002}} is raised if the input cannot be parsed or converted to the final data type.
* Updated: errors are using {{Code|text/plain}} as media-type.
Bureaucrats, editor, reviewer, Administrators
13,550

edits

Navigation menu