HTTP API design

[Till Westmann <ti...@apache.org>]

Hi,

I\u2019ve 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

Re: HTTP API design

[Mike Carey <dt...@gmail.com>]

+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\u2019ve 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