+1 -- that result-handling (so to speak) scheme looks nice/clean to me.
Cheers,
Mike
On 3/11/17 7:33 PM, Till Westmann wrote:
Hi,
I’ve just updated our wiki page for the HTTP API [1] while working on a
patch to modify the APIs in a corresponding way.
One modification is to the path to the endpoints. The paths are now:
/query/service
(was "/query" on the wiki and "/query/service" in the code)
/query/service/status
(was "/status" on the wiki and "/query/status" in the code)
/query/service/result
(was "/results" on the wiki and "/query/result" in the code)
The second modification is to the way we specify result handles. In the
current code result handles are described by a JSON document, e.g.
{"handle":[23,2]}
where 23 is the job id and 2 is the result set id (actually we usually
only
have the result set id 0, as it's quite tricky to create a job with more
than one result set in AsterixDB). Passing this JSON document as a
parameter to a GET request is actually quite ugly, as the curly braces,
quotes, colon, and angle brackets have to be URL encoded. This leads to
command lines like this:
$ curl
http://localhost:19002/query/status?handle=%7B%22handle%22%3A%5B23%2C2%5D%7D
In the design [1], we already had anticipated to use UUIDs (which do not
require URL encoding as all used characters are unreserved characters
[2])
instead on the JSON documents to specify result handles. In the current
modification, I've further simplified this to just use the combination of
job id and result set id, separated by a dash, as an identifier. A
corresponding command line would be:
$ curl http://localhost:19002/query/service/status/23-2
It seemed that just using the existing identifier for result set would be
1) sufficient (the identifiers are transient and should be opaque anyway)
and
2) simpler to implement as we don't need an additional mapping from
UUIDs to
the existing identifiers.
Thoughts/concerns/better ideas?
Cheers,
Till
[1]
https://cwiki.apache.org/confluence/display/ASTERIXDB/New+HTTP+API+Design
[2] https://tools.ietf.org/html/rfc3986
