REST Procedure Call
Generates wrappers to REST-like HTTP APIs
- (define-method (procedure-name path-arg... #!key query-arg...) uri-or-request body-writer body-reader header-reader) syntax
Generates scheme procedures that call the underlying HTTP API with the parameters given.
Creates a procedure procedure-name that calls the HTTP API specified in uri-or-request.
Arguments specified in path-arg are appended, in the order they appear, to the end of the URI, separated by /. Arguments specified as symbols will be turned into mandatory positional arguments to the procedure procedure-name. These argument values will end up in the correct place in the API call when procedure-name is called. Arguments specified strings will be placed into the URL in the correct position as constants and cannot be changed during calls to procedure-name.
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.
If body-writer is specified then an extra argument is appended to the path-args and is also mandatory.
When 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.
When all the preparations have been made, the URL is then fetched via call-with-input-request. call-with-input-request remains free inside define-method so will bind to whichever procedure is bound in the environment from which define-method is called. This means that, by (use ...)ing the correct module, you can use the regular call-with-input-request from http-client or you can use the version from oauth which signs the requests in the appropriate manner. 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.
When header-reader is specified, procedure-name returns three results: the result of the call to header-reader, the result of the call to reader and a list containing the uri and response objects. When header-reader is not specified, procedure-name returns just the latter two values.
header-reader is optional. If it is supplied, it is called as a procedure with the response headers as its only argument. The result of the call to this procedure is then returned as the first result of the procedure-name call.
See dropbox-lolevel.scm file for more examples.
Here we bind to
The Dropbox API docs specify the response as JSON so we read it with read-json from medea. The request uses the GET method and has no body so we substitute #f for the writer procedure.
The Dropbox API requires the requests to be signed with oauth so use (use oauth-client) which provides a call-with-input-request that will sign the requests for us.
(use rest-bind oauth-client) (define-method (metadata root path #!key file_limit hash list include_deleted rev locale) "https://api.dropbox.com/1/metadata/" #f read-json)
Here we bind to
...which just causes the generated procedure to return the contents of the Chicken Homepage.
This "API" does not require the requests to be signed with oauth, so we want the method to use the regular call-with-input request from http-client.
(use rest-bind http-client) (define-method (homepage) "https://www.call-cc.org/" #f (cut read-string #f <>))
Here we bind to
This "API" has an argument in the middle of the URL and the constant parts "money" and "ticker" follow.
(use rest-bind http-client medea)
(define-method (btc-ticker currency "money" "ticker") "https://data.mtgox.com/api/2" #f read-json)
Copyright (C) 2012, Andy Bennett All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- 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.
- 0.2, (2013/02/18) : Support the retriving of headers from the response object. This release also includes some bonus bugfixes and documentation updates.
- 0.3, (2013/03/03) : Fix up misunderstandings in the .setup and .release-info file that were preventing v0.2 from chicken-installing properly.
- 0.4, (2014/05/04) : Add support for APIs that have constant path-fragments after the arguments. See Example 3 for how to use this.
- 0.5, (2014/05/09) : Preserve the ordering of the bound arguments.