source: project/wiki/eggref/4/http-client @ 15566

Last change on this file since 15566 was 15566, checked in by sjamaan, 10 years ago

Add docs about raw data string

File size: 6.9 KB
Line 
1[[tags: egg]]
2
3== http-client
4
5[[toc:]]
6
7=== Description
8
9Http-client is a highlevel HTTP client library.
10
11=== Author
12
13[[Peter Bex]]
14
15=== Requirements
16
17Requires the [[intarweb]] and [[openssl]] extensions.
18
19=== Documentation
20
21This egg is still very much under development; the API should be
22considered to be unstable and can change heavily from version to
23version.
24
25==== Main request procedures
26
27<procedure>(call-with-response request writer reader)</procedure>
28
29This is the core http-client procedure.  It is only necessary to use
30this when you want the most control over the request/response cycle.
31{{request}} is the request object that contains information about the
32request to perform.  {{reader}} is a procedure that receives the
33response object and should read the request body, {{writer}} is a
34procedure that receives the request object and should write the
35request body.
36
37The {{writer}} should be prepared to be called several times; if the
38response is a redirect or some other status that indicates the server
39wants the client to perform a new request, the writer should be ready
40to write a request body for this new request.
41
42Returns three values: The result of the call to {{reader}}, the
43request-uri of the last request and the response object. The
44request-uri is useful because this is to be used as the base uri of
45the document. This can differ from the initial request in the presence
46of redirects.
47
48<procedure>(call-with-input-request uri-or-request writer reader)</procedure>
49
50This procedure is a convenience wrapper around {{call-with-response}}.
51
52It is much less strict - {{uri-or-request}} can be an [[intarweb]]
53request object, but also an uri-common object or even a string with the
54URI in it, in which case a request object will be automatically
55constructed around the URI, using the {{GET}} method.
56
57{{writer}} can be either {{#f}} (in which case nothing is written), a
58string containing the raw data to send, an alist (in which case the
59data is written out as using www-form-urlencoding, useful for POST
60requests), or a procedure that accepts a port and writes the response
61data to it.  If you supply a procedure, do not forget to set the
62{{content-length}} header!  In the other cases, the length is
63calculated and the header automatically set for you.
64
65{{reader}} is a procedure which accepts a port and reads out the data.
66
67Returns three values: The result of the call to {{reader}}, the
68request-uri of the last request and the response object.  If the
69response code is not in the 200 class, it will throw an exception of
70type {{(exn http client-error)}}, {{(exn http server-error)}} or
71{{(exn http unexpected-server-response)}}, depending on the response
72code.  This includes {{404 not found}} (which is a {{client-error}}).
73
74<procedure>(with-input-request uri-or-request write-thunk read-thunk)</procedure>
75
76Same as {{call-with-input-request}}, except this accepts thunks
77(lambdas of no arguments) which will be executed with the current
78input (or output) port to the request or response port, respectively.
79
80<examples>
81<example>
82<init>(use http-client)</init>
83<expr>(with-input-from-request "http://chicken.wiki.br/" #f read-string)</expr>
84<result>"[the chicken wiki page HTML contents]"</result>
85</example>
86<example>
87<init>(use http-client uri-common intarweb)</init>
88<expr>
89;; Perform a POST of the key "test" with value "value" to an echo service
90(with-input-from-request
91  (make-request method: 'POST
92                uri: (uri-reference "http://localhost/echo-service"))
93  '((test . "value")) read-string)
94</expr>
95<result>"You posted: test=value"</result>
96</example>
97</examples>
98
99
100==== Parameters
101
102<parameter>(max-retry-attempts [number])</parameter>
103
104When a request fails because of an I/O or network problem (or simply
105because the remote end closed a persistent connection while we were
106doing something else), the library will try to establish a new
107connection and perform the request again.  This parameter controls how
108many times this is allowed to be done.  If {{#f}}, it will never give up.
109
110Defaults to 1.
111
112<parameter>(retry-request? [predicate])</parameter>
113
114This procedure is invoked when a retry should take place, to determine
115if it should take place at all.  It should be a procedure accepting a
116request object and returning {{#f}} or a true value.  If the value is
117true, the new request will be sent.  Otherwise, the error that caused
118the retry attempt will be re-raised.
119
120Defaults to {{idempotent?}}, from [[intarweb]].  This is because
121non-idempotent requests cannot be safely retried when it is unknown
122whether the previous request reached the server or not.
123
124<parameter>(max-redirect-depth [number])</parameter>
125
126The maximum number of allowed redirects, or {{#f}} if there is no
127limit.  Currently there's no automatic redirect loop detection
128algorithm implemented.
129
130Defaults to 5.
131
132<parameter>(client-software [software-spec])</parameter>
133
134This is the names, versions and comments of the software packages that
135the client is using, for use in the {{user-agent}} header which is
136automatically added to each request.
137
138Defaults to {{(("Chicken Scheme HTTP-client" VERSION #f))}}, where
139{{VERSION}} is the version of this egg.
140
141
142==== Connection management
143
144<procedure>(close-connection! uri)</procedure>
145
146Close the connection to the server associated with the URI.
147
148<procedure>(close-all-connections!)</procedure>
149
150Close all connections to all servers.
151
152
153==== Cookie management
154
155TODO
156
157
158=== Changelog
159
160* 0.1 Initial version
161
162=== License
163
164  Copyright (c) 2008-2009, Peter Bex
165  Parts copyright (c) 2000-2004, Felix L. Winkelmann
166  All rights reserved.
167 
168  Redistribution and use in source and binary forms, with or without
169  modification, are permitted provided that the following conditions are
170  met:
171 
172  Redistributions of source code must retain the above copyright
173  notice, this list of conditions and the following disclaimer.
174 
175  Redistributions in binary form must reproduce the above copyright
176  notice, this list of conditions and the following disclaimer in the
177  documentation and/or other materials provided with the distribution.
178 
179  Neither the name of the author nor the names of its contributors may
180  be used to endorse or promote products derived from this software
181  without specific prior written permission.
182 
183  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
184  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
185  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
186  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
187  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
188  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
189  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
190  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
191  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
192  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
193  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
194  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.