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

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

Change description of conditions thrown by http-client

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