{ "ns" : "http://zorba.io/modules/http-client", "description" : "

\n This module provides functions for performing HTTP requests.\n

\n

A simple GET request using the get#1 convenience function

\n 
\n import module namespace http=\"http://zorba.io/modules/http-client\";\n http:get(\"http://www.example.com\")\n
\n

\n This example makes a GET request to example.com and returns the server's response\n as a JSON object.\n

\n 
\n {\n   \"status\" : 200,\n   \"message\" : \"OK\",\n   \"headers\" : {\n     \"Content-Length\" : \"1270\",\n     \"Date\" : \"Tue, 11 Jun 2013 22:27:10 GMT\",\n     ...\n   },\n   \"body\" : {\n     \"media-type\" : \"text/html\",\n     \"content\" : \"...\"\n   }\n }\n
\n

Response format

\n

Most functions in this module (all except options#1)\n return a single JSON item, describing the server's response, as in the previous\n example.\n The server status (integer) and message (string) fields are always present.\n If the server replied sending one or more headers, they are reported\n in an optional headers object. Each header is represented as a single (string)\n field.

\n

For non-multipart responses, as in the previous example, the response body,\n if any, is reported as a body object. This object contains both the (string)\n media-type returned by the server and its content.\n The type of the content field is determined by the media-type returned by the\n server. If the media-type indicates that the body content is textual,\n then the content has type string, base64Binary otherwise.\n Specifically, the body content is considered textual only if the MIME-type specified in\n the media-type is one of:\n

\n or if the MIME-type starts with \"text/\" or ends with \"+xml\".

\n

For multipart responses, multiple bodies are returned, as in the following example:

\n 
\n {\n   \"status\" : 200,\n   \"message\" : \"OK\",\n   \"headers\" : {\n     \"Date\" : \"Tue, 11 Jun 2013 22:34:13 GMT\",\n     ...\n   },\n   \"multipart\" : {\n     \"boundary\": \"--AaB03x\",\n     \"parts\": [\n       {\n         \"headers\" : {\n            \"Content Disposition: file\",\n            ...\n         },\n         \"body\": {\n           \"media-type\" : \"image/gif\",\n           \"content\" : \"...\"\n         }\n       },\n       {\n         \"body\" : {\n           \"media-type\" : \"text/html\",\n           \"content\" : \"...\"\n         }\n       }\n    ]\n }\n
\n

The multipart field contains both the boundary used to separate parts\n and an array containing all parts. Each part contains its specific headers,\n if any, and the corresponding body.

\n

Important Notice Regarding Nondeterministic Functions

\n

\n The following functions in this module -\n get#1,\n get-text#1,\n get-binary#1,\n send-nondeterministic-request-1,\n head#1, and\n options#1\n are declared to be nondeterministic, which means that their results\n will not be cached.\n However, they are not declared to be\n sequential, which means that they may be re-ordered during query optimization.\n According to the HTTP RFC, GET, HEAD an OPTIONS requests should not have any side-effects.\n However, in practice it is not uncommon, especially for GET requests, to have side-effects.\n If your application depends on the ordering of side-effects from requests issued through\n these functions, you should either use the send-request()\n function (which is declared sequential), or alternatively\n wrap each call to get() in your own sequential function, to ensure\n that the requests are not reordered.\n

\n

$href Arguments to Functions

\n

Several functions in this module accept a URL argument named $href. In\n all cases, the value passed to $href must be a valid anyURI.\n However, all functions declare $href to be of type string. This\n is for convenience, since you can pass a string literal value (that\n is, a URL in double-quotes spelled out explicitly in your query)\n to an string parameter.

\n

Relation to the EXPath http-client module

\n

EXPath defines its own http-client\n module, which is available separately.\n There are two primary differences between EXPath's http-client and\n this module:\n

    \n
  1. EXPath defines only the send-request() function, although it\n does include convenient 1- and 2-argument forms in addition to the\n full 3-argument form. EXPath does not include the simpler get(),\n post(), put(), delete(), head(), and options() functions defined by\n this module.
    2. \n
  2. EXPath uses XML to represent request for its send-request() function,\n whereas this module uses JSON.
    3. \n
  3. EXPath specifies that all XML content returned by an HTTP server\n will be parsed and returned as an XML document, whereas all HTML content\n will be tidied up into valid XML, and then parsed into an element.\n This module returns any textual content as string and any binary content\n as base6Binary.
    4. \n
  4. EXPath accepts XML nodes as body in the send-request() function and\n automatically serializes them into a string. The send-request() function\n defined in this module only allows string, base64Binary, and hexBinary\n as body types.\n
    5. \n
\n

\n

\n See the full spec\n of the EXPath http-client module for more information.\n

\n", "sees" : [ "XQuery 1.1: Function Declaration" ], "authors" : [ "Federico Cavalieri" ], "version" : null, "encoding" : "utf-8", "namespaces" : [ { "uri" : "http://zorba.io/annotations", "prefix" : "an" }, { "uri" : "http://www.w3.org/2005/xqt-errors", "prefix" : "err" }, { "uri" : "http://zorba.io/modules/http-client", "prefix" : "http" }, { "uri" : "http://jsoniq.org/function-library", "prefix" : "libjn" }, { "uri" : "http://zorba.io/options/versioning", "prefix" : "ver" } ], "functions" : [ { "arity" : 1, "name" : "delete", "qname" : "http:delete", "signature" : "($href as string) as object()", "description" : "

\n This function makes an HTTP DELETE request to a given URL.\n

\n", "summary" : "

\n This function makes an HTTP DELETE request to a given URL.

", "annotation_str" : " %an:sequential", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "sequential", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "href", "type" : "string", "occurence" : null, "description" : "
The URL to which the request will be made (see note above).
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified request is not valid.", "http:TIMEOUT A timeout occurred waiting for the response." ] }, { "arity" : 1, "name" : "get-binary", "qname" : "http:get-binary", "signature" : "($href as string) as object()", "description" : "

\n This function makes a GET request on a given URL. All returned bodies\n are forced to be interpreted as binary data, and will be returned\n as base64Binary items.\n

\n", "summary" : "

\n This function makes a GET request on a given URL.

", "annotation_str" : " %an:nondeterministic", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "nondeterministic", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "href", "type" : "string", "occurence" : null, "description" : "
The URL to which the request will be made (see note above).
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified href is not valid.", "http:TIMEOUT A timeout occurred waiting for the response." ] }, { "arity" : 1, "name" : "get-text", "qname" : "http:get-text", "signature" : "($href as string) as object()", "description" : "

\n This function makes a GET request to a given URL. All returned bodies\n are forced to be interpreted as textual, with a UTF-8 charset and will\n be returned as string items.\n

\n", "summary" : "

\n This function makes a GET request to a given URL.

", "annotation_str" : " %an:nondeterministic", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "nondeterministic", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "href", "type" : "string", "occurence" : null, "description" : "
The URL to which the request will be made (see note above).
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified href is not valid.", "http:TIMEOUT A timeout occurred waiting for the response." ] }, { "arity" : 1, "name" : "get", "qname" : "http:get", "signature" : "($href as string) as object()", "description" : "

\n This function makes a GET request to a given URL.\n

\n", "summary" : "

\n This function makes a GET request to a given URL.

", "annotation_str" : " %an:nondeterministic", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "nondeterministic", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "href", "type" : "string", "occurence" : null, "description" : "
The URL to which the request will be made (see note above).
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified href is not valid.", "http:TIMEOUT A timeout occurred waiting for the response." ] }, { "arity" : 1, "name" : "head", "qname" : "http:head", "signature" : "($href as string) as object()", "description" : "

\n This function makes an HTTP HEAD request on a given URL.\n

\n", "summary" : "

\n This function makes an HTTP HEAD request on a given URL.

", "annotation_str" : " %an:nondeterministic", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "nondeterministic", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "href", "type" : "string", "occurence" : null, "description" : "
The URL to which the request will be made (see note above).
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified href is not valid.", "http:TIMEOUT A timeout occurred waiting for the response." ] }, { "arity" : 1, "name" : "options", "qname" : "http:options", "signature" : "($href as string) as string*", "description" : "

\n This function makes an HTTP OPTIONS request, which asks the server\n which operations it supports.\n

\n", "summary" : "

\n This function makes an HTTP OPTIONS request, which asks the server\n which operations it supports.

", "annotation_str" : " %an:nondeterministic", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "nondeterministic", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "href", "type" : "string", "occurence" : null, "description" : "
The URL to which the request will be made (see note above).
" } ], "returns" : { "type" : "string*", "description" : "A sequence of string values of the allowed operations." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified href is not valid.", "http:TIMEOUT A timeout occurred waiting for the response." ] }, { "arity" : 2, "name" : "post", "qname" : "http:post", "signature" : "($href as string, $body as atomic) as object()", "description" : "

\n This function makes an HTTP POST request to a given URL.\n

\n

\n The body passed to this function must be either a string, a base64Binary, or an\n hexBinary.\n If it is a string, the Content-Type sent to the server will be \"text/plain\",\n \"application/octet-stream\" otherwise.\n

\n", "summary" : "

\n This function makes an HTTP POST request to a given URL.

", "annotation_str" : " %an:sequential", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "sequential", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "href", "type" : "string", "occurence" : null, "description" : "
The URL to which the request will be made (see note above).
" }, { "name" : "body", "type" : "atomic", "occurence" : null, "description" : "
The body which will be sent to the server.
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified request is not valid.", "http:TIMEOUT A timeout occurred waiting for the response." ] }, { "arity" : 3, "name" : "post", "qname" : "http:post", "signature" : "($href as string, $body as atomic, $content-type as string) as object()", "description" : "

\n This function makes an HTTP POST request to a given URL.\n

\n

\n The body passed to this function must be either a string, a base64Binary,\n or an hexBinary.\n In any case, Content-Type of the request sent to the server will\n be $content-type.\n

\n", "summary" : "

\n This function makes an HTTP POST request to a given URL.

", "annotation_str" : " %an:sequential", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "sequential", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "href", "type" : "string", "occurence" : null, "description" : "
The URL to which the request will be made (see note above).
" }, { "name" : "body", "type" : "atomic", "occurence" : null, "description" : "
The body which will be sent to the server
" }, { "name" : "content-type", "type" : "string", "occurence" : null, "description" : "
The content type of the body as described above.
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified request is not valid.", "http:TIMEOUT A timeout occurred waiting for the response.", "http:CHARSET The specified charset is unsupported." ] }, { "arity" : 2, "name" : "put", "qname" : "http:put", "signature" : "($href as string, $body as atomic) as object()", "description" : "

\n This function makes an HTTP PUT request to a given URL.\n

\n

\n The body passed to this function must be either a string, a base64Binary or\n an hexBinary.\n If it is a string, the Content-Type sent to the server will be \"text/plain\",\n \"application/octet-stream\" otherwise.\n

\n", "summary" : "

\n This function makes an HTTP PUT request to a given URL.

", "annotation_str" : " %an:sequential", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "sequential", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "href", "type" : "string", "occurence" : null, "description" : "
The URL to which the request will be made (see note above).
" }, { "name" : "body", "type" : "atomic", "occurence" : null, "description" : "
The body which will be sent to the server.
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified request is not valid.", "http:TIMEOUT A timeout occurred waiting for the response." ] }, { "arity" : 3, "name" : "put", "qname" : "http:put", "signature" : "($href as string, $body as atomic, $content-type as string) as object()", "description" : "

\n This function makes an HTTP PUT request to a given URL.\n

\n

\n The body passed to this function must be either a string, a base64Binary, or\n an hexBinary.\n In any case, Content-Type of the request sent to the server will\n be $content-type.\n

\n", "summary" : "

\n This function makes an HTTP PUT request to a given URL.

", "annotation_str" : " %an:sequential", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "sequential", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "href", "type" : "string", "occurence" : null, "description" : "
The URL to which the request will be made (see note above).
" }, { "name" : "body", "type" : "atomic", "occurence" : null, "description" : "
The body which will be sent to the server.
" }, { "name" : "content-type", "type" : "string", "occurence" : null, "description" : "
The content type of $body to send to the server.
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified request is not valid.", "http:TIMEOUT A timeout occurred waiting for the response.", "http:CHARSET The specified charset is unsupported." ] }, { "arity" : 1, "name" : "send-nondeterministic-request", "qname" : "http:send-nondeterministic-request", "signature" : "($request as object()) as object()", "description" : "

\n This function sends an HTTP request and returns the corresponding response.\n

\n

\n This function has the same semantics of send-request-1,\n but is declared as nondeterministic and thus should only be used when\n the request has no side-effects.\n

\n", "summary" : "

\n This function sends an HTTP request and returns the corresponding response.

", "annotation_str" : " %an:nondeterministic", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "nondeterministic", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "request", "type" : "object()", "occurence" : null, "description" : "
see request parameter of send-request#1
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified request is not valid.", "http:TIMEOUT A timeout occurred waiting for the response.", "http:FOLLOW Cannot follow a redirect of a POST, PUT, or DELETE request.", "http:CHARSET The specified charset is unsupported." ] }, { "arity" : 1, "name" : "send-request", "qname" : "http:send-request", "signature" : "($request as object()) as object()", "description" : "

\n This function sends an HTTP request and returns the corresponding response.\n

\n

\n This function is declared as sequential and should be used whenever the\n request may have side-effects.\n

\n

\n The request parameters are specified in the $request JSON object, which\n has the following minimal structure:\n 

\n   {\n     \"href\": \"http://www.example.com\"\n   }\n
\n

\n

This object specifies a GET request of the URI \"http://www.example.com\"

\n

Additional optional parameters can be specified when issuing a request,\n using the following structure:

\n 
\n  {\n    \"method\": \"POST\",\n    \"href\": \"http://www.example.com\",\n    \"authentication\":\n    {\n      \"username\" : \"user\",\n      \"password\" : \"pass\",\n      \"auth-method\" : \"Basic\"\n    },\n    \"options\":\n    {\n      \"status-only\": true,\n      \"override-media-type\": \"text/plain\",\n      \"follow-redirect\": false,\n      \"timeout\": 30,\n      \"user-agent\": \"Mozilla/5.0\"\n    },\n    \"headers\":\n    {\n      \"name\": \"value\",\n      ...\n    },\n    \"body\":\n    {\n      \"media-type\": \"text/plain\",\n      \"content\": \"...\"\n    }\n  }\n
\n

\n The method field (string) defines the HTTP verb to use in the HTTP request (i.e., GET, HEAD, OPTIONS,\n POST, PUT, DELETE). If not specified GET will be used.\n The authentication field can be used to specify the credentials and authentication method\n used when issuing a request (e.g, Basic). If the authentication field is specified, all its (string)\n subfields must be specified. If an authentication object is provided, it overrides any\n Authorization header specified in the request.\n Additionally, the following options can be specified:\n

\n

\n

One or more headers can be sent to the server, specifying them in an optional headers object.\n Each header is represented as a single (string) field. These headers are overridden if the corresponding\n option/authentication has been specified in the request.

\n

For non-multipart request a body object can be specified.\n This object must contain both the desired (string) media-type and its content.\n The type of the content field must be either string, base64Binary, or hexBinary.

\n

For multipart requests, multipart object can be specified in place of the body object.\n The multipart object has the following structure:

\n 
\n  \"multipart\" : {\n    \"boundary\": \"--AaB03x\",\n    \"parts\": [\n      {\n        \"headers\" : {\n           \"Content Disposition: file\",\n           ...\n        },\n        \"body\": {\n          \"media-type\" : \"image/gif\",\n          \"content\" : \"...\"\n        }\n      },\n      {\n        \"body\" : {\n          \"media-type\" : \"text/html\",\n          \"content\" : \"...\"\n        }\n      }\n   ]\n }\n
\n

The multipart field contains an optional (string) field which specifies\n the boundary used to separate each part and an array containing all parts.\n Each part contains its specific headers, if any, and the corresponding body.\n

\n", "summary" : "

\n This function sends an HTTP request and returns the corresponding response.

", "annotation_str" : " %an:sequential", "annotations" : [ { "prefix" : "an", "ns" : "http://zorba.io/annotations", "name" : "sequential", "value" : "" } ], "updating" : false, "parameters" : [ { "name" : "request", "type" : "object()", "occurence" : null, "description" : "
a JSON http-client request object
" } ], "returns" : { "type" : "object()", "description" : "standard http-client return type." }, "errors" : [ "http:HTTP An HTTP error occurred.", "http:REQUEST The specified request is not valid.", "http:TIMEOUT A timeout occurred waiting for the response.", "http:FOLLOW Cannot follow a redirect of a POST, PUT, or DELETE request.", "http:CHARSET The specified charset is unsupported." ] } ], "variables" : [ ] }