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

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

Fix typo

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