Read the wiki on the new API, I would suggest all *plans *be in a JSONObject format, therefore it can be parsed and presented in Javascript. Apart from that on first glance it looks great.
I can start writing a Swagger IO config on the new HTTP API Design, shall I go ahead with that? Cheers, Kaveen On 21 April 2016 at 04:04, Till Westmann <[email protected]> wrote: > I’ve updated the document [1] to reflect the suggestions (no warnings yet). > > Also, there’s another change that makes "include-results" and the "mode" > more independent. When including results in an async request, the final > response from the status endpoint will include the results. Otherwise the > final response from the status endpoint will contain a handle. > > Please check the doc and tell me what you think. > > Cheers, > Till > > [1] > https://cwiki.apache.org/confluence/display/ASTERIXDB/New+HTTP+API+Design > > On 15 Apr 2016, at 17:32, Ildar Absalyamov wrote: > > Till, >> >> All the comments make sense to me except for warnings. I was struggling >> to remember anything in Asterix, which would resemble the warnings >> described by you. >> As a future extension we could support that, but in this document I was >> trying to reflect current state of Asterix functionality + some extensions >> which were on horizon for a long time and are really needed. >> >> On Apr 15, 2016, at 14:37, Till Westmann <[email protected]> wrote: >>> >>> 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 >>>> >>> >> Best regards, >> Ildar >> >
