Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

rest-bind
  1. Outdated egg!
  2. rest-bind
    1. Description
    2. Source Code
    3. Author
    4. Requirements
    5. API
      1. define-method
    6. Examples
      1. 1
      2. 2
      3. 3
    7. License
    8. Version History

Description

REST Procedure Call

Generates wrappers to REST-like HTTP APIs

Source Code

https://bitbucket.org/knodium/rest-bind

Author

Andy Bennett

Requirements

None

API

define-method

[syntax] (define-method (procedure-name path-arg... #!key query-arg...) uri-or-request body-writer body-reader header-reader)

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.

Examples

1

See dropbox-lolevel.scm file for more examples.

Here we bind to

   https://api.dropbox.com/1/metadata/<root>/<path>?file_limit=<>&...

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)

2

Here we bind to

   http://www.call-cc.org

...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 <>))

3

Here we bind to

   https://data.mtgox.com/api/2/<currency>/money/ticker

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)

License

 
 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.

Version History