asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Till Westmann" <ti...@apache.org>
Subject HTTP API design
Date Sun, 12 Mar 2017 03:33:41 GMT
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

Mime
View raw message