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

Last change on this file since 15115 was 15115, checked in by sjamaan, 11 years ago

Update docs to new API

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