Hi Ildar,
thanks for writing all of this up!
A few comments/proposals:
- Request:
- For the "format" parameter, I think that it would be nice to
support
both, the parameter and the Accept header, as it’s sometimes much
more
convenient to pass a parameter than a HTTP header. However, I think
that
the HTTP header should override the parameter if they conflict.
- "execute-query" could be renamed to "execute-statement" to be
consistent
with the "statement" parameter.
- Response:
- I'm wondering if "results" should be able to get a URI for the
handle or
if we should have another field in the response for that (e.g.
"handle"). The advantage of 2 fields would be that the consumer
knows
how to parse each field (either as a URI or as an array).
- Inside of the "metrics" object I would only expect simple numbers.
For
the plans we could have another top-level field ("plan"?) an object
that
contains the different plans ..
- It would also be nice to add a new top-level field for warnings.
That
could be used to report warnings from the engine that evaluates the
statement. And it could also be used to report unused parameters
(assuming that the default behavior for a parameter that is passed
in,
but not understood by the server is simply ignored).
Thoughts?
Cheers,
Till
On 14 Apr 2016, at 15:23, Ildar Absalyamov wrote:
Hi Devs,
Recently there have been a number of conversations about the future of
our REST (aka HTTP) API. I summarized these discussions in an outline
of the new API design:
https://cwiki.apache.org/confluence/display/ASTERIXDB/New+HTTP+API+Design
<https://cwiki.apache.org/confluence/display/ASTERIXDB/New+HTTP+API+Design>.
The need to refactor existing API came from different directions (and
from different people), and is explained in motivation section. Thus I
believe it’s about the time to take an effort and improve existing
API, so that it will not drag us down in the future. However during
the transition step I believe it would be better to keep exiting API
endpoints, so that we would not break people’s current experimental
setup.
It would be good to know feedback from the folks, who have been
contributing to that part of the systems recently.
Best regards,
Ildar
