basis/http/client/client-docs.factor

   1 USING: http help.markup help.syntax io.files io.streams.string
   2 io.encodings.8-bit io.encodings.binary kernel strings urls
   3 urls.encoding byte-arrays strings assocs sequences ;
   4 IN: http.client
   5
   6 HELP: download-failed
   7 { $error-description "Thrown by " { $link http-request } " if the server returns a status code other than 200. The " { $slot "response" } " and " { $slot "body" } " slots can be inspected for the underlying cause of the problem." } ;
   8
   9 HELP: too-many-redirects
  10 { $error-description "Thrown by " { $link http-request } " if the server returns a chain of than " { $link max-redirects } " redirections." } ;
  11
  12 HELP: <get-request>
  13 { $values { "url" "a " { $link url } " or " { $link string } } { "request" request } }
  14 { $description "Constructs an HTTP GET request for retrieving the URL." }
  15 { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
  16
  17 HELP: <post-request>
  18 { $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "request" request } }
  19 { $description "Constructs an HTTP POST request for submitting post data to the URL." }
  20 { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
  21
  22 HELP: download
  23 { $values { "url" "a " { $link url } " or " { $link string } } }
  24 { $description "Downloads the contents of the URL to a file in the " { $link current-directory } " having the same file name." }
  25 { $errors "Throws an error if the HTTP request fails." } ;
  26
  27 HELP: download-to
  28 { $values { "url" "a " { $link url } " or " { $link string } } { "file" "a pathname string" } }
  29 { $description "Downloads the contents of the URL to a file with the given pathname." }
  30 { $errors "Throws an error if the HTTP request fails." } ;
  31
  32 HELP: http-get
  33 { $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
  34 { $description "Downloads the contents of a URL." }
  35 { $errors "Throws an error if the HTTP request fails." } ;
  36
  37 HELP: http-post
  38 { $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
  39 { $description "Submits a form at a URL." }
  40 { $errors "Throws an error if the HTTP request fails." } ;
  41
  42 HELP: with-http-get
  43 { $values { "url" "a " { $link url } " or " { $link string } } { "quot" { $quotation "( chunk -- )" } } { "response" response } }
  44 { $description "Downloads the contents of a URL. Chunks of data are passed to the quotation as they are read." }
  45 { $errors "Throws an error if the HTTP request fails." } ;
  46
  47 HELP: http-request
  48 { $values { "request" request } { "response" response } { "data" sequence } }
  49 { $description "Sends an HTTP request to an HTTP server, and reads the response." }
  50 { $errors "Throws an error if the HTTP request fails." } ;
  51
  52 HELP: with-http-request
  53 { $values { "request" request } { "quot" { $quotation "( chunk -- )" } } { "response" response } }
  54 { $description "Sends an HTTP request to an HTTP server, and reads the response incrementally. Chunks of data are passed to the quotation as they are read." }
  55 { $errors "Throws an error if the HTTP request fails." } ;
  56
  57 ARTICLE: "http.client.get" "GET requests with the HTTP client"
  58 "Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
  59 { $subsection http-get }
  60 "Utilities to retrieve a " { $link url } " and save the contents to a file:"
  61 { $subsection download }
  62 { $subsection download-to }
  63 "Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
  64 { $subsection <get-request> }
  65 { $subsection http-request }
  66 "The " { $link http-get } " 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:"
  67 { $subsection with-http-get }
  68 { $subsection with-http-request } ;
  69
  70 ARTICLE: "http.client.post" "POST requests with the HTTP client"
  71 "As with GET requests, there is a high-level word which takes a " { $link url } " and a lower-level word which constructs an HTTP request object which can be passed to " { $link http-request } ":"
  72 { $subsection http-post }
  73 { $subsection <post-request> }
  74 "Both words take a post data parameter, which can be one of the following:"
  75 { $list
  76     { "a " { $link byte-array } " or " { $link string } " is sent the server without further encoding" }
  77     { "an " { $link assoc } " is interpreted as a series of form parameters, which are encoded with " { $link assoc>query } }
  78     { { $link f } " denotes that there is no post data" }
  79 } ;
  80
  81 ARTICLE: "http.client.encoding" "Character encodings and the HTTP client"
  82 "The " { $link http-request } ", " { $link http-get } " and " { $link http-post } " words output a sequence containing data that was sent by the server."
  83 $nl
  84 "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."
  85 $nl
  86 "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."
  87 $nl
  88 "For any other MIME type, the " { $link binary } " encoding is assumed, and thus the data is returned literally in a byte array." ;
  89
  90 ARTICLE: "http.client.errors" "HTTP client errors"
  91 "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:"
  92 { $subsection download-failed }
  93 { $subsection too-many-redirects } ;
  94
  95 ARTICLE: "http.client" "HTTP client"
  96 "The " { $vocab-link "http.client" } " vocabulary implements an HTTP and HTTPS client on top of " { $link "http" } "."
  97 $nl
  98 "For HTTPS support, you must load the " { $vocab-link "urls.secure" } " vocab first. If you don't load it, HTTPS will not load and images generated by " { $vocab-link "tools.deploy" } " will be smaller as a result."
  99 $nl
 100 "There are two primary usage patterns, data retrieval with GET requests and form submission with POST requests:"
 101 { $subsection "http.client.get" }
 102 { $subsection "http.client.post" }
 103 "More esoteric use-cases, for example HTTP methods other than the above, are accomodated by constructing an empty request object with " { $link <request> } " and filling everything in by hand."
 104 { $subsection "http.client.encoding" }
 105 { $subsection "http.client.errors" }
 106 { $see-also "urls" } ;
 107
 108 ABOUT: "http.client"