(index ("define-method" 0))
(def (sig (syntax "(define-method (procedure-name path-arg... #!key query-arg...) uri-or-request body-writer body-reader header-reader)" (id define-method))) (p "Generates scheme procedures that call the underlying HTTP API with the parameters given.") (p "Creates a procedure " (tt "procedure-name") " that calls the HTTP API specified in " (tt "uri-or-request") ".") (p "Arguments specified in " (tt "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 " (tt "procedure-name") ". These argument values will end up in the correct place in the API call when " (tt "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 " (tt "procedure-name") ".") (p "Arguments specified in " (tt "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 " (tt "procedure-name") " is called.") (p "If " (tt "body-writer") " is specified then an extra argument is appended to the " (tt "path-arg") "s and is also mandatory.") (p "When the " (tt "procedure-name") " is called, the arguments are put into the URL. If " (tt "body-writer") " is specified then it it is called with the value of the last postitional argument (" (tt "path-arg") "). " (tt "body-writer") " should return something suitable for use as the " (tt "writer") " argument of " (tt "call-with-input-request") ".") (p "When all the preparations have been made, the URL is then fetched via " (tt "call-with-input-request") ". " (tt "call-with-input-request") " remains free inside define-method so will bind to whichever procedure is bound in the environment from which " (tt "define-method") " is called. This means that, by (use ...)ing the correct module, you can use the regular " (tt "call-with-input-request") " from " (int-link "http-client") " or you can use the version from " (int-link "oauth") " which signs the requests in the appropriate manner. If " (tt "body-writer") " is not specified then the GET method is implied. If " (tt "body-writer") " is specified then the POST method is implied. If the HTTP API calls for another method then " (tt "uri-or-request") " must be specified using " (tt "make-request") " from " (int-link "intarweb") ". " (tt "body-reader") " is passed as the " (tt "reader") " argument to " (tt "call-with-input-request") ". The result of " (tt "body-reader") " is one of the results of the call to " (tt "procedure-name") ".") (p "When " (tt "header-reader") " is specified, " (tt "procedure-name") " returns three results: the result of the call to " (tt "header-reader") ", the result of the call to " (tt "reader") " and a list containing the " (tt "uri") " and " (tt "response") " objects. When " (tt "header-reader") " is not specified, " (tt "procedure-name") " returns just the latter two values.") (p (tt "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 " (tt "procedure-name") " call."))
