Commits

Andy Bennett  committed b6df35a

Wiki documentation

A quick write-up of what we can do so far.

Signed-off-by: Andy Bennett <andyjpb@knodium.com>

  • Participants
  • Parent commits f407a03

Comments (0)

Files changed (1)

File rest-bind.svnwiki

+[[tags: egg]]
+
+== rest-bind
+
+[[toc:]]
+
+=== Description
+
+REST Procedure Call
+
+Generates wrappers to REST-like HTTP APIs
+
+=== Author
+
+[[/users/andyjpb|Andy Bennett]]
+
+=== Requirements
+
+* [[data-structures]] [[srfi-1]]
+
+=== API
+
+==== define-method
+
+<syntax>(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 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-arg}}s 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 [[https://bitbucket.org/knodium/dropbox/src/e7929501b4fe2fee4c5e821cfc925b22bb51825d/dropbox-lolevel.scm|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
+* 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.
+