basis/http/client/client-docs.factor

   1 USING: assocs byte-arrays destructors help.markup help.syntax http
   2 http.client.post-data http.client.private
   3 io.encodings.binary io.encodings.latin1 io.pathnames kernel
   4 sequences strings urls urls.encoding ;
   5 IN: http.client
   6
   7 HELP: download-failed
   8 { $error-description "Thrown by " { $link http-request } " if the server returns a status code other than 200. The " { $slot "response" } " slot can be inspected for the underlying cause of the problem." } ;
   9
  10 HELP: too-many-redirects
  11 { $error-description "Thrown by " { $link http-request } " if the server returns a chain of than " { $link max-redirects } " redirections." } ;
  12
  13 HELP: invalid-proxy
  14 { $error-description "Thrown by " { $link http-request } " if the proxy url is not valid." } ;
  15
  16 HELP: <get-request>
  17 { $values { "url" { $or url string } } { "request" request } }
  18 { $description "Constructs an HTTP GET request for retrieving the URL." }
  19 { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
  20
  21 HELP: <post-request>
  22 { $values { "post-data" object } { "url" { $or url string } } { "request" request } }
  23 { $description "Constructs an HTTP POST request for submitting post data to the URL." }
  24 { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
  25
  26 HELP: <head-request>
  27 { $values { "url" { $or url string } } { "request" request } }
  28 { $description "Constructs an HTTP HEAD request for retrieving the URL." }
  29 { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
  30
  31 HELP: <delete-request>
  32 { $values { "url" { $or url string } } { "request" request } }
  33 { $description "Constructs an HTTP DELETE request for the requested URL." }
  34 { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
  35
  36 HELP: <options-request>
  37 { $values { "url" { $or url string } } { "request" request } }
  38 { $description "Constructs an HTTP OPTIONS request for the requested URL." }
  39 { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
  40
  41 HELP: <trace-request>
  42 { $values { "url" { $or url string } } { "request" request } }
  43 { $description "Constructs an HTTP TRACE request for the requested URL." }
  44 { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
  45
  46 HELP: http-get
  47 { $values { "url" { $or url string } } { "response" response } { "data" sequence } }
  48 { $description "Downloads the contents of a URL." }
  49 { $errors "Throws an error if the HTTP request fails." } ;
  50
  51 HELP: http-get*
  52 { $values { "url" { $or url string } } { "response" response } { "data" sequence } }
  53 { $description "Downloads the contents of a URL, but does not check the HTTP response code for success." } ;
  54
  55 { http-get http-get* } related-words
  56
  57 HELP: http-post
  58 { $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } }
  59 { $description "Submits an HTTP POST request." }
  60 { $errors "Throws an error if the HTTP request fails." } ;
  61
  62 HELP: http-post*
  63 { $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } }
  64 { $description "Submits an HTTP POST request, but does not check the HTTP response code for success." } ;
  65
  66 { http-post http-post* } related-words
  67
  68 HELP: http-put
  69 { $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } }
  70 { $description "Submits an HTTP PUT request." }
  71 { $errors "Throws an error if the HTTP request fails." } ;
  72
  73 HELP: http-put*
  74 { $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } }
  75 { $description "Submits an HTTP PUT request, but does not check the HTTP response code for success." } ;
  76
  77 { http-put http-put* } related-words
  78
  79 HELP: http-head
  80 { $values { "url" { $or url string } } { "response" response } { "data" sequence } }
  81 { $description "Same as " { $link http-get } " except that the server is not supposed to return a message-body in the response, as per RFC2616. However in practise, most web servers respond to GET and HEAD method calls with identical responses." }
  82 { $errors "Throws an error if the HTTP request fails." } ;
  83
  84 HELP: http-head*
  85 { $values { "url" { $or url string } } { "response" response } { "data" sequence } }
  86 { $description "Same as " { $link http-get* } " except that the server is not supposed to return a message-body in the response, as per RFC2616. However in practise, most web servers respond to GET and HEAD method calls with identical responses." } ;
  87
  88 { http-head http-head* } related-words
  89
  90 HELP: http-delete
  91 { $values { "url" { $or url string } } { "response" response } { "data" sequence } }
  92 { $description "Requests that the origin server delete the resource identified by the URL." }
  93 { $errors "Throws an error if the HTTP request fails." } ;
  94
  95 HELP: http-delete*
  96 { $values { "url" { $or url string } } { "response" response } { "data" sequence } }
  97 { $description "Requests that the origin server delete the resource identified by the URL, but does not check the HTTP response code for success." } ;
  98
  99 { http-delete http-delete* } related-words
 100
 101 HELP: http-options
 102 { $values { "url" { $or url string } } { "response" response } { "data" sequence } }
 103 { $description "Submits an HTTP OPTIONS request." }
 104 { $errors "Throws an error if the HTTP request fails." } ;
 105
 106 HELP: http-options*
 107 { $values { "url" { $or url string } } { "response" response } { "data" sequence } }
 108 { $description "Submits an HTTP OPTIONS request, but does not check the HTTP response code for success." } ;
 109
 110 { http-options http-options* } related-words
 111
 112 HELP: http-patch
 113 { $values { "patch-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } }
 114 { $description "Submits an HTTP PATCH request." }
 115 { $errors "Throws an error if the HTTP request fails." } ;
 116
 117 HELP: http-patch*
 118 { $values { "patch-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } }
 119 { $description "Submits an HTTP PATCH request, but does not check the HTTP response code for success." } ;
 120
 121 { http-patch http-patch* } related-words
 122
 123 HELP: http-trace
 124 { $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
 125 { $description "Submits an HTTP TRACE request." }
 126 { $errors "Throws an error if the HTTP request fails." } ;
 127
 128 HELP: http-trace*
 129 { $values { "url" { $or url string } } { "response" response } { "data" sequence } }
 130 { $description "Submits an HTTP TRACE request, but does not check the HTTP response code for success." } ;
 131
 132 { http-trace http-trace* } related-words
 133
 134 HELP: http-request
 135 { $values { "request" request } { "response" response } { "data" sequence } }
 136 { $description "A variant of " { $link http-request* } " that checks that the response was successful." }
 137 { $errors "Throws an error if the HTTP request fails." } ;
 138
 139 HELP: http-request*
 140 { $values { "request" request } { "response" response } { "data" sequence } }
 141 { $description "Sends an HTTP request to an HTTP server, and reads the response." } ;
 142
 143 HELP: read-response-header
 144 { $values { "response" response } }
 145 { $description "Initializes the 'header', 'cookies', 'content-type', 'content-charset' and 'content-encoding' field of the response." } ;
 146
 147 HELP: with-http-request
 148 { $values { "request" request } { "quot" { $quotation ( chunk -- ) } } { "response/stream" "a response or a stream" } }
 149 { $description "A variant of " { $link do-http-request } " that checks that the response was successful." } ;
 150
 151 { http-request http-request* with-http-request } related-words
 152
 153 ARTICLE: "http.client.get" "GET requests with the HTTP client"
 154 "Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
 155 { $subsections
 156     http-get
 157     http-get*
 158 }
 159 "To download to a file, see the " { $link "http.download" } " vocabulary."
 160
 161 "Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
 162 { $subsections
 163     <get-request>
 164     http-request
 165     http-request*
 166 }
 167 "The " { $link http-request } " and " { $link http-request* } " words output sequences. This is undesirable if the response data may be large. Another pair of words take a quotation instead, and pass the quotation chunks of data incrementally:"
 168 { $subsections
 169     with-http-request
 170 } ;
 171
 172 ARTICLE: "http.client.post-data" "HTTP client post data"
 173 "HTTP POST and PUT request words take a post data parameter, which can be one of the following:"
 174 { $list
 175     { "a " { $link byte-array } ": the data is sent the server without further encoding" }
 176     { "a " { $link string } ": the data is encoded and then sent as a series of bytes" }
 177     { "an " { $link assoc } ": the assoc is interpreted as a series of form parameters, which are encoded with " { $link assoc>query } }
 178     { "an input stream: the contents of the input stream are transmitted to the server without being read entirely into memory - this is useful for large requests" }
 179     { { $link f } " denotes that there is no post data" }
 180     { "a " { $link post-data } " tuple, for additional control" }
 181 }
 182 "When passing a stream, you must ensure the stream is closed afterwards. The best way is to use " { $link with-disposal } " or " { $link "destructors" } ". For example,"
 183 { $code
 184   "\"my-large-post-request.txt\" ascii <file-reader>"
 185   "[ URL\" http://www.my-company.com/web-service\" http-post ] with-disposal"
 186 }
 187 "An internal word used to convert objects to " { $link post-data } " instances:"
 188 { $subsections >post-data } ;
 189
 190 ARTICLE: "http.client.post" "POST requests with the HTTP client"
 191 "Basic usage involves passing post data and a " { $link url } ", and getting a " { $link response } " and data back:"
 192 { $subsections http-post http-post* }
 193 "Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
 194 { $subsections <post-request> }
 195 "Both words take a post data parameter; see " { $link "http.client.post-data" } "." ;
 196
 197 ARTICLE: "http.client.put" "PUT requests with the HTTP client"
 198 "Basic usage involves passing post data and a " { $link url } ", and getting a " { $link response } " and data back:"
 199 { $subsections http-put http-put* }
 200 "Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
 201 { $subsections <put-request> }
 202 "Both words take a post data parameter; see " { $link "http.client.post-data" } "." ;
 203
 204 ARTICLE: "http.client.head" "HEAD requests with the HTTP client"
 205 "Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
 206 { $subsections http-head http-head* }
 207 "Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
 208 { $subsections
 209     <head-request>
 210 } ;
 211
 212 ARTICLE: "http.client.delete" "DELETE requests with the HTTP client"
 213 "Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
 214 { $subsections http-delete http-delete* }
 215 "Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
 216 { $subsections
 217     <delete-request>
 218 } ;
 219
 220 ARTICLE: "http.client.options" "OPTIONS requests with the HTTP client"
 221 "Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
 222 { $subsections http-options http-options* }
 223 "Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
 224 { $subsections
 225     <options-request>
 226 }
 227 "RFC2616 does not define any use for an entity body, yet allows for the inclusion of one as part of the OPTIONS method. This is not supported with this version of the " { $vocab-link "http.client" } ". The current implementation of " { $link http-options } " only supports a " { $link url } " request with no corresponding post-data, as per the stack effect." ;
 228
 229 ARTICLE: "http.client.trace" "TRACE requests with the HTTP client"
 230 "Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
 231 { $subsections http-trace http-trace* }
 232 "Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
 233 { $subsections
 234     <trace-request>
 235 } ;
 236
 237 ARTICLE: "http.client.encoding" "Character encodings and the HTTP client"
 238 "The " { $link http-request } ", " { $link http-get } " and " { $link http-post } " words output a sequence containing data that was sent by the server."
 239 $nl
 240 "If the server specifies a " { $snippet "content-type" } " header with a character encoding, the HTTP client decodes the data using this character encoding, and the sequence will be a string."
 241 $nl
 242 "If no encoding was specified but the MIME type is a text type, the " { $link latin1 } " encoding is assumed, and the sequence will be a string."
 243 $nl
 244 "For any other MIME type, the " { $link binary } " encoding is assumed, and thus the data is returned literally in a byte array." ;
 245
 246 ARTICLE: "http.client.errors" "HTTP client errors"
 247 "HTTP operations may fail for one of two reasons. The first is an I/O error resulting from a network problem; a name server lookup failure, or a refused connection. The second is a protocol-level error returned by the server. There are two such errors:"
 248 { $subsections
 249     download-failed
 250     too-many-redirects
 251 } ;
 252
 253 ARTICLE: "http.client" "HTTP client"
 254 "The " { $vocab-link "http.client" } " vocabulary implements an HTTP and HTTPS client on top of " { $link "http" } "."
 255 $nl
 256 "For HTTPS support, you must load the " { $vocab-link "io.sockets.secure" } " vocab first. If you don't need HTTPS support, don't load " { $vocab-link "io.sockets.secure" } "; this will reduce the size of images generated by " { $vocab-link "tools.deploy" } "."
 257 $nl
 258 "There are two primary usage patterns, data retrieval with GET requests and form submission with POST requests:"
 259 { $subsections
 260     "http.client.get"
 261     "http.client.post"
 262     "http.client.put"
 263 }
 264 "Submission data for POST and PUT requests:"
 265 { $subsections "http.client.post-data" }
 266 "Other HTTP methods are also supported:"
 267 { $subsections
 268     "http.client.head"
 269     "http.client.delete"
 270     "http.client.options"
 271     "http.client.trace"
 272 }
 273 "More esoteric use-cases, for example HTTP methods other than the above, are accommodated by constructing an empty request object with " { $link <request> } " and filling everything in by hand."
 274 { $subsections
 275     "http.client.encoding"
 276     "http.client.errors"
 277 }
 278 "For authentication, only Basic Access Authentication is implemented, using the username/password from the target or proxy url. Alternatively, the " { $link set-basic-auth } " or " { $link set-proxy-basic-auth } " words can be called on the " { $link request } " object."
 279 $nl
 280 "The http client can use an HTTP proxy transparently, by using the " { $link "http.proxy-variables" } ". Additionally, the proxy variables can be ignored by setting the " { $slot "proxy-url" } " slot of each " { $link request } " manually:"
 281 { $list
 282     { "Setting " { $slot "proxy-url" } " to " { $link f } " prevents http.client from using a proxy." }
 283     { "Setting the slots of the default empty url in " { $slot "proxy-url" } " overrides the corresponding values from the proxy variables." }
 284 }
 285
 286 { $see-also "urls" } ;
 287
 288 ABOUT: "http.client"