Loading TOC...

xdmp:http-post

xdmp:http-post(
   $uri as xs:string,
   [$options as (element()|map:map)?],
   [$data as node()?]
) as item()+

Summary

Sends an http POST request to the server.

Parameters
$uri The URI to which the data is to be posted.
$options Options with which to customize this operation. You can specify options as either an XML element in the "xdmp:http" namespace, or as a map:map. The options names below are XML element localnames. When using a map, replace the hyphens with camel casing. For example, "an-option" becomes "anOption" when used as a map:map key. This function supports the following options, plus the options from the xdmp:http-get function.

<data>

This option can contain any string. Anything in the data option is sent as a string in the PUT or POST body. When POSTing to a web service, the data may need to be a SOAP XML structure, a JSON structure, or binary content. The optional third argument can be used to specify the body instead.

The other options are the same as the other xdmp:http-* functions, and the options are documented with the xdmp:http-get $options parameter.

$data The data for this request. This is an alternative to the data option for the second parameter that allows binary content to be specified for the body of the POST.

Required Privileges

http://marklogic.com/xdmp/privileges/xdmp-http-post

Usage Notes

The http functions only operate on URIs that use the http or https schemes; specifying a URI that does not begin with http:// or https:// throws an exception.

If an http function times out, it throws a socket received exception (SVC-SOCRECV).

The function returns a sequence containing the request response. If the reponse is multi-part, then the sequence contains multiple items.

If you expect the request body from this http function to be processed by another application (via a web service, for example), you should specify a content-type header. If no content-type header is specified, the content type defaults to text/plain.

Example

xdmp:http-post("http://www.my.com/document.xhtml",
     <options xmlns="xdmp:http">
       <authentication method="basic">
         <username>myname</username>
         <password>mypassword</password>
       </authentication>
     </options>)
=> the response from the server as well as the specified document

Example

(: Use xdmp:quote to encode the XML as a string
   because the <data> options element is a string :)
let $payload := xdmp:quote(
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'
  xmlns:xsd='http://www.w3.org/2001/XMLSchema'
  xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
  xmlns:SOAP-ENC='http://schemas.xmlsoap.org/soap/encoding/'
  xmlns:my='urn:MyConnection'>
 <SOAP-ENV:Body>
   <my:LogOn>
     <my:User>user</my:User>
     <my:Password>pass</my:Password>
     <my:Ticket>abc123</my:Ticket>
     <my:newData>1234</my:newData>
   </my:LogOn>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
)
return
xdmp:http-post("http://www.my.com/document.xhtml",
     <options xmlns="xdmp:http">
       <authentication method="basic">
         <username>myname</username>
         <password>mypassword</password>
       </authentication>
       <data>{$payload}</data>
       <headers>
         <content-type>application/xml</content-type>
       </headers>
     </options>)
=> the response from the server as well as the specified document

Example

xquery version "1.0-ml";

let $payload := 
 '{ "user-name": "joe",
       "password": "cool"
       ,"role": [ "rest-reader" , "rest-writer" ]
  }' 
return
xdmp:http-post("http://localhost:8002/manage/v2/users?format=json",
     <options xmlns="xdmp:http">
       <authentication method="digest">
         <username>myname</username>
         <password>mypassword</password>
       </authentication>
       <data>{$payload}</data>
     </options>)
=> the response from the server, and in this example, the new user (joe) is 
   created

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.

Comments

The commenting feature on this page is enabled by a third party. Comments posted to this page are publicly visible.
  • If the response of http-post function is more than 2GB, it is throwing XDMP-TOOBIG error ("Document size exceeds text document size limit of 2048 megabytes"). Is there any way to handle it?
    • Chunk it into pieces on the fly in a streaming way, and save chunks instead of trying to save the entire 2Gb as one document..
  • top tip - If you perform a sequence of xdmp:http-post calls they will become async in operation eg. with no guarantee of order of return, unless you force read of a result. In most cases this is a useful optimisation but can come as a surprise if you are expecting serial processing.
    • hi jim, thank you for this warning. Can you (or anyone willing) give an example of how to force read a result? If i nest an xdmp:http-post call inside another function, will that guarantee the inner xdmp:http-post will be completed ahead of the outer call? If not, can you point me to the right direction to accomplish this. Not sure of what search terms i should google and research on. Many thanks. I am a newbie attempting to do a mash-up of 3 web services into one web-page.
      • It may be sufficient to access the response. For instance, let $response := xdmp:http-post(...) let $headers := $response[1] If that doesn't work, take a look at xdmp:eager()