You are looking at historical revision 27779 of this page. It may differ significantly from its current revision.

rest-bind

Description

REST Procedure Call

Generates wrappers to REST-like HTTP APIs

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

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

procedure-name currently returns the result of call-with-input-request.

header-reader is optional and currently ignored. It is intended that this be a procedure that can extract any required headers from the response.

Examples

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.

   (define-method (metadata root path #!key file_limit hash list include_deleted rev locale)
   "https://api.dropbox.com/1/metadata/"
   #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