From f928a49c8a8ab5ed04a961f9489ef2b8d7201c3d Mon Sep 17 00:00:00 2001 From: Kevin Morris Date: Thu, 10 Feb 2022 00:16:32 -0800 Subject: [PATCH] doc(rpc): Request Types -> Request Methods & reword description The POST description was ridiculously confusing. This cleans up the doc a bit and is hopefully a bit more straight-forward. Signed-off-by: Kevin Morris --- doc/rpc.txt | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/doc/rpc.txt b/doc/rpc.txt index ebd7e485..b5219399 100644 --- a/doc/rpc.txt +++ b/doc/rpc.txt @@ -28,21 +28,27 @@ Package information can be obtained by issuing HTTP GET requests of the form +/rpc?v=5&type=info&arg[]=_pkg1_&arg[]=_pkg2_&...+ where _pkg1_, _pkg2_, ... are the names of packages to retrieve package details for. -Request Types -------------- +Request Methods +--------------- -The GET method here parses arguments in an odd way due to `v=5` historically -supporting this ordering. Later versions will remove support for this kind -of parsing, and the POST method is our first step toward solving it. +Historically, the `type=multiinfo` `v=5` GET request has supported a +particular ordering of arguments. The POST request argument ordering +cannot be guaranteed, and so its behavior is different. Differences are +described below: -* `GET` - - Search arguments are constructed using the last found argument(s). - If the last related argument is `arg[]`, we collect arguments from - end to start until we hit a non-`arg[]` argument. If the last related - argument is `arg`, it used as the one and only argument. -* `POST` - - Search arguments are constructed using `[arg] + args` where - `args == arg[]`. +`GET`:: + `type=multiinfo` arguments are parsed by iterating the query string + from last to first key, looking for an `arg` or `arg[]`. Once one is + found, behavior diverges depending on which is found first: the `arg` + parameter is used as the sole argument or the `arg[]` parameters are + built into a list until a non-argument key is encountered. +`POST (experimental)`:: + All provided instances of `arg` and `arg[]` given to `type=multiinfo` + are supported in unison: + + curl -d 'v=5' -d 'type=info' -d 'arg=one' -d 'arg[]=two' -d 'arg[]=three' ... + +All other valid query types are supported without change. Examples --------