Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
| valign='top' | '''Summary'''|Sends an HTTP request and interprets the corresponding response. <code>:* {{Code|$request</code> }} contains the parameters of the HTTP request such as HTTP method and headers. * In addition to this it can also contain the URI to which the request will be sent and the body of the HTTP method. * If the URI is not given with the parameter <code>{{Code|$href</code>}}, its value in <code>{{Code|$request</code> }} is used instead. * The structure request body can also be supplied via the {{Code|$bodies}} parameter. Notes:* Both basic and digest authentication is supported.* While the contents of <code>the request can be supplied as child of the {{Code|http:request</code> body}} element follows , 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' | '''NotesErrors'''|The attribute {{Error|HC0001|#Errors}} an HTTP error occurred.<br/>{{Error|HC0002|#Errors}} error parsing the entity content as XML or HTML.<codebr/>auth{{Error|HC0003|#Errors}} with a multipart response, the override-media-type must be either a multipart media type or application/octet-methodstream.<br/code> of {{Error|HC0004|#Errors}} the src attribute on the body element is mutually exclusive with all other attribute (except the media-type).<codebr/>${{Error|HC0005|#Errors}} the requestelement is not valid.<br/code> is not considered in our implementation because we are handling only basic authentication{{Error|HC0006|#Errors}} a timeout occurred waiting for the response.
==Examples==
===Status Only===Simple GET request. As the attribute <code>{{Code|status-only</code> }} is set to true, only the response element is returned.
===Google Homepage=== Retrieve the Google search home pagewith a timeout of 10 seconds. In order to [[http://home.ccil.org/~cowan/XML/tagsoup/ Parsers#HTML_Parser|parse HTML]], TagSoup] must be referenced contained in the class path in order to parse html.
<script>window.google={kEI:"rZB- ... </script> </center>
===POST Request===
<query xmlns="http://basex.org/rest"> <text><![CDATA[ <html>{ for $i in 1 to 3 return <div>Section {$i }</div> }</html> ]]></text> </query>
→Google Homepage
This [[XQuery ModulesModule Library|XQuery Module]] contains a single function to send HTTP requests and handle HTTP responses. The function <code>{{Code|send-request<}} is based on the [http://expath.org/spec/code>http-client EXPath HTTP Client Module]. It gives full control over the available request and response parameters. For simple GET requests, which is introduced with the [[Fetch Module]] may be sufficient. If <code><http:header name="Accept-Encoding" value="gzip"/></code> prefixis specified and if the addressed web server provides support for the {{Code|gzip}} compression algorithm, is linked the response will automatically be decompressed. =Conventions= All functions in this module are assigned to the statically declared <code><nowiki>http://expath.org/ns/http-client</nowiki></code> namespace and based on , which is statically bound to the {{Code|http}} prefix.<br/>All errors are assigned to the [<code><nowiki>http://expath.org/specns/error</nowiki></http-client EXPath HTTP Client Module]:code> namespace, which is statically bound to the {{Code|exerr}} prefix. =Functions=
==http:send-request==
{|width='100%'
|-
| valign='top' width='90120' | '''Signatures'''|<code><b>{{Func|http:send-request</b>(|$request as element(http:request)?, $href as xs:string?, $bodies as item()*) as |item()+</code>}}<br/><code><b>{{Func|http:send-request</b>(|$request as element(http:request)) ?, $href as xs:string?|item()+</code>}}<br /><code><b>{{Func|http:send-request</b>(|$request as element(http:request)?, $href as xs:string?, $bodies as item() as *|item()+</code>}}<br />
|-
|-
|}
'''Query:'''
</http:response></pre>
'''Query:'''
<pre class="brush:xquery">http:send-request(<http:request method='get' href='http://www.google.com' timeout='10'/>)</pre>
'''Result:'''
<pre class="brush:xml">
<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>
</pre>
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 class="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"/>
</http:request>
)[2]
return try {
html:parse($binary)
} catch * {
'Conversion to XML failed: ' || $err:description
}
</pre>
===SVG Data===
Content-type ending with +xml, e.g. image/svg+xml.
</svg></pre>
POST request to the BaseX REST Service, specifying a username and password.
method='post' username='admin' password='admin' send-authorization='true'>
<http:body media-type='application/xml'>
</http:body>
</http:request>
</pre>
=Errors= {| class="wikitable" width="100%"! width="110"|Code|Description|-|{{Code|HC0001}}|An HTTP error occurred.|-|{{Code|HC0002}}|Error parsing the entity content as XML or HTML.|-|{{Code|HC0003}}|With a multipart response, the override-media-type must be either a multipart media type or application/octet-stream.|-|{{Code|HC0004}}|The src attribute on the body element is mutually exclusive with all other attribute (except the media-type).|-|{{Code|HC0005}}|The request element is not valid.|-|{{Code|HC0006}}|A timeout occurred waiting for the response.|} =Changelog= ;Version 9.0* Updated: support for gzipped content encoding ;Version 8.0* Added: digest authentication ;Version 7.6* Updated: [[Category#http:send-request|http:XQuerysend-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.
