Bureaucrats, editor, reviewer, Administrators
13,554
edits
Changes
Jump to navigation
Jump to search
m
===Status Only===
===Google Homepage=== Retrieve the Google search home pagewith a timeout of 10 seconds. In order to [[http://home.ccil.org/~cowan/XML/tagsoup/ Parsers#HTMLParser|parse HTML]], TagSoup] must be contained in the class path in order to parse html.
<script>window.google={kEI:"rZB- ... </script> </center>
===POST Request===
[[Category:XQuery]]
Text replacement - "syntaxhighlight" to "pre"
This [[Module Library|XQuery Module]] contains a single function to send HTTP requests and handle HTTP responses. The function {{Code|send-request}} is based on the [http://expath.org/spec/http-client EXPath HTTP Client Module]. It gives full control over the available request and response parameters. For simple GET requests, the [[Fetch Module]] may be sufficient.
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.
Please note that BaseX provides extensions to the specification:
* Since {{Announce|Version 11}}, {{Code|csv}}, {{Code|json}} and {{Code|html}} parser options can be supplied to influence the conversion of the response.
Since BaseX 10, the module is based on the [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=
All functions in this module are assigned to the {{Code|<code><nowiki>http://expath.org/ns/http-client}} </nowiki></code> namespace, which is statically bound to the {{Code|http}} prefix.<br/>All errors are assigned to the {{Code|<code><nowiki>http://expath.org/ns/error}} </nowiki></code> namespace, which is statically bound to the {{Code|exerrexperr}} prefix.
=Functions=
==http:send-request==
{{Announce|Updated with Version 11:}} {{Code|csv}}, {{Code|json}}, {{Code|html}} and {{Code|text}} attributes added.
{| width='100%'
|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>http:send-request|( $request as element(http:request)?, $href as xs:string? := (), $bodies as item()*|item()+}}<br/>{{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 /pre>|-valign="top"
| '''Summary'''
|Sends an HTTP request and interprets the corresponding response. :* {{Code|$request}} contains the parameters of the HTTP an {{Code|<http:request such as HTTP />}} element with a {{Code|method }} attribute, an {{Code|href}} attribute with the target URI, and optional header and headersbody elements. In addition * The request is either sent to this it can also contain the URI of the {{Code|$href}} argument or (if empty) to which the request will be sent and URI supplied via the body of the HTTP method{{Code|href}} attribute. If * In addition to the URI is not given with attributes of the parameter official specification, {{Code|$hrefcsv}}, {{Code|json}}, its value in {{Code|$requesthtml}} and {{Code|text}} attributes can be supplied to define how to convert the response body (see [[#Response Conversion|Response Conversion]] for an example). Notes:* Both basic and digest authentication is used insteadsupported.<br/>The structure * While the contents of the request can be supplied as child of the {{Code|http:requestbody}} element follows , it is faster and safer to pass them on via the third argument.* Certificate verification can be globally disabled via the {{Option|IGNORECERT}} option.* For further information, please check out the [http://expath.org/spec/http-client EXPath] specification. Since {{Version|8.0}}, digest authentication is supported as well.|-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.
|}
=Examples= ==ExamplesStatus Only==
Simple GET request. As the attribute {{Code|status-only}} is set to true, only the response element is returned.
'''Query:'''
<pre classlang="brush:'xquery"'>http:send-request(<http:request method='get' status-only='true'/>, 'http://basex.org')</pre>
'''Result:'''
<pre classlang="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:response></pre>
'''Query:'''
<pre classlang="brush:'xquery"'>http:send-request(<http:request method='get' href='http://www.google.com' timeout='10'/>)</pre>
'''Result:'''
<pre classlang="brush:xml">
<http:response status="200" message="OK">
<http:header name="Date" value="Mon, 14 Mar 2011 22:03:25 GMT"/>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="contentContent-typeType" content="text/html; charset=ISO-8859UTF-18"/>
<title>Google</title>
</body>
</html>
'''Query:'''
<pre classlang="brush:'xquery"'>
let $binary := http:send-request(
<http:request method='get'
override-media-type='application/octet-stream'
href='http://www.google.com'>
<http:header name="User-Agent" value="Opera"/>
===SVG Data===
Content-type ending with +xml, e.g. image/svg+xml.
'''Query:'''
<pre classlang="brush:'xquery"'>http:send-request(<http:request method='get'/>, 'http://upload.wikimedia.org/wikipedia/commons/6/6b/Bitmap_VS_SVG.svg')</pre>
'''Result:'''
<pre classlang="brush:xml"><http:response status="200" message="OK">
<http:header name="ETag" value="W/"11b6d-4ba15ed4""/>
<http:header name="Age" value="9260"/>
</svg></pre>
POST request to the BaseX REST Service, specifying a username and password.
'''Query:'''
<pre classlang="brush:'xquery"'>let $http:send-request :=( <http:request href='http://localhost:8984/rest' method='post' username='admin' password='admin' send-authorization='true'> <http:body media-type='application/xml'/> <query xmlns="/http:request>, 'http://basex.orglocalhost:8080/rest"', <query> <text><![CDATA[ <html>{ for $i in 1 to 3 return <div>Section {$i }</div> }</html> ]]> </text> </query> </http:body> </http:request>return http:send-request($request)
</pre>
'''Result:'''
<pre classlang="brush:xml">
<http:response xmlns:http="http://expath.org/ns/http-client" status="200" message="OK">
<http:header name="Content-Length" value="135"/>
</html>
</pre>
==File Upload==
Performs an HTML file upload. In the RESTXQ code, the uploaded file is written to the temporary directory:
'''Query:'''
<pre lang='xquery'>
let $path := 'file-to-be.uploaded'
return http:send-request(
<http:request method='POST'>
<http:multipart media-type='multipart/form-data'>
<http:header name='content-disposition'
value='form-data; name="files"; filename="{ file:name($path) }"'/>
<http:body media-type='application/octet-stream'/>
</http:multipart>
</http:request>,
'http://localhost:8080/write-to-temp',
file:read-binary($path)
)
</pre>
'''RESTXQ service:'''
<pre lang='xquery'>
declare
%rest:POST
%rest:path('/write-to-temp')
%rest:form-param('files', '{$files}')
function dba:file-upload(
$files as map(xs:string, xs:base64Binary)
) as empty-sequence() {
map:for-each($files, function($file, $content) {
file:write-binary(file:temp-dir() || $file, $content)
});
};
</pre>
==Response Conversion==
CSV, JSON and HTML responses are automatically converted to an XML representation. The target format can be influenced by supplying {{Code|csv}}, {{Code|json}} and {{Code|html}} attributes:
'''Query:'''
<pre lang='xquery'>
http:send-request(<http:request method='GET' href='http://localhost:8080/json' json='format=xquery,lax=true'/>)
</pre>
'''Result:'''
<pre lang="javascript">
map { "abcde": 12345 }
</pre>
Without the {{Code|json}} attribute, the response body is converted to the default XML representation:
<pre lang="xml">
<json type="object">
<abcde>12345</abcde>
</json>
</pre>
'''RESTXQ service:'''
<pre lang='xquery'>
declare
%rest:path('json')
%output:method('json')
function local:json() {
map { 'abcde': 12345 }
};
</pre>
See the [[CSV Module]], [[JSON Module]] and [[HTML Module]] for a list of the available options.
=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 11.0
* Updated: {{Function||http:send-request}}: {{Code|csv}}, {{Code|json}}, {{Code|html}} and {{Code|text}} attributes added.
;Version 10.0
* Updated: Implementation based on the new [https://openjdk.org/groups/net/httpclient/intro.html Java HTTP Client].
;Version 9.0
* Updated: support for gzipped content encoding
;Version 8.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.
