chickadee » rest-bind » define-method

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