source: project/wiki/eggref/4/rest-bind @ 27779

Last change on this file since 27779 was 27779, checked in by Mario Domenech Goulart, 8 years ago

rest-bind (wiki): remove core units from Requirements section

File size: 4.3 KB
Line 
1[[tags: egg]]
2
3== rest-bind
4
5[[toc:]]
6
7=== Description
8
9REST Procedure Call
10
11Generates wrappers to REST-like HTTP APIs
12
13=== Author
14
15[[/users/andyjpb|Andy Bennett]]
16
17=== Requirements
18
19None
20
21=== API
22
23==== define-method
24
25<syntax>(define-method (procedure-name path-arg... #!key query-arg...) uri-or-request body-writer body-reader header-reader</syntax>
26
27Generates scheme procedures that call the underlying HTTP API with the parameters given.
28
29Creates a procedure {{procedure-name}} that calls the HTTP API specified in {{uri-or-request}}. Arguments specified in {{path-arg}} are appended, in the other they appear, to the end of the URI, separated by /. These areguments are mandatory. Arguments specified in {{query-arg}} are optional and, if present are placed in the query string. They are named as they appear in the definition. Their value is that as given when {{procedure-name}} is called.
30
31If body-writer is specified then an extra argument is appended to the {{path-arg}}s and is also mandatory.
32
33When the {{procedure-name}} is called, the arguments are put into the URL. If {{body-writer}} is specified then it it is called with the value of the last postitional argument ({{path-arg}}). {{body-writer}} should return something suitable for use as the {{writer}} argument of {{call-with-input-request}}.
34
35When all the preparations have been made, the URL is then fetched via {{call-with-input-request}} from [[http-client]]. If {{body-writer}} is not specified then the GET method is implied. If {{body-writer}} is specified then the POST method is implied. If the HTTP API calls for another method then {{uri-or-request}} must be specified using {{make-request}} from [[intarweb]]. {{body-reader}} is passed as the {{reader}} argument to {{call-with-input-request}}. The result of {{body-reader}} is one of the results of the call to {{procedure-name}}.
36
37{{procedure-name}} currently returns the result of call-with-input-request.
38
39{{header-reader}} is optional and currently ignored. It is intended that this be a procedure that can extract any required headers from the response.
40
41=== Examples
42
43See [[https://bitbucket.org/knodium/dropbox/src/e7929501b4fe2fee4c5e821cfc925b22bb51825d/dropbox-lolevel.scm|dropbox-lolevel.scm]] file for more examples.
44
45Here we bind to
46    https://api.dropbox.com/1/metadata/<root>/<path>?file_limit=<>&...
47
48The Dropbox API docs specify the response as JSON so we read it with
49read-json from [[medea]]. The request uses the GET method and has no
50body so we substitute #f for the writer procedure.
51
52    (define-method (metadata root path #!key file_limit hash list include_deleted rev locale)
53    "https://api.dropbox.com/1/metadata/"
54    #f
55    read-json)
56
57
58=== License
59
60  Copyright (C) 2012, Andy Bennett
61  All rights reserved.
62 
63  Redistribution and use in source and binary forms, with or without
64  modification, are permitted provided that the following conditions are met:
65 
66  Redistributions of source code must retain the above copyright notice, this
67  list of conditions and the following disclaimer.
68  Redistributions in binary form must reproduce the above copyright notice,
69  this list of conditions and the following disclaimer in the documentation
70  and/or other materials provided with the distribution.
71  Neither the name of the author nor the names of its contributors may be
72  used to endorse or promote products derived from this software without
73  specific prior written permission.
74 
75  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
76  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
77  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
78  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
79  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
80  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
81  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
82  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
83  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
84  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
85  POSSIBILITY OF SUCH DAMAGE.
86
87=== Version History
88* 0.1, (2012/11/04) : Preliminary support for binding to HTTP REST APIs. We don't currently support the sending of request bodies or the reading of custom response headers.
Note: See TracBrowser for help on using the repository browser.