Till Westmann has posted comments on this change. Change subject: Document the Query Service API ......................................................................
Patch Set 1: (3 comments) https://asterix-gerrit.ics.uci.edu/#/c/1698/1/asterixdb/asterix-doc/src/site/markdown/api.md File asterixdb/asterix-doc/src/site/markdown/api.md: Line 45: $ curl -v --data-urlencode "statement=select 1;" \ > I would suggest using a slightly more interesting query here - partly to ma I'm not sure. All of he API-specific encoding is done by the --data-urlencode option of curl (and I think that the description for "statement" should clarify that better). So all the encoding issues that we would illustrate here would actually be shell encoding issues - which are shell dependent and not API dependent. And they also would not apply for all other uses of the API in applications (which hopefully is the main use-case). So I think that having a simple query with an understandable command line here is a better solution. PS1, Line 47: client_context_id > could we have more explanation about the `client_context_id` and its usage? This is just a user-defined sequence of characters that the API receives and returns unchanged. One way this can be used is to match individual requests, jobs, and responses (as in the case of the cancellation API). Another option could be to use it for groups of requests if an application decides to put e.g. an group identifier into that field. We should probably expose the value in the logs as well so that once could use it to match e.g. an error in a query to the application's business process that used the query to retrieve data. Does this make sense? Line 157: $ curl -v http://localhost:19002/query/service/status/9-0 > What is the /9-0 suffix here? It should be completely opaque to the user - this is just something one gets as a handle from a previous call. II should at least write that. Maybe we shouldn't even document these endpoints as one should never construct an URL for these in an application (but we probably need to document the shape of the result somehow). Thoughts? -- To view, visit https://asterix-gerrit.ics.uci.edu/1698 To unsubscribe, visit https://asterix-gerrit.ics.uci.edu/settings Gerrit-MessageType: comment Gerrit-Change-Id: Ifcefb1671ea305a5958c9a74a588b4aaa17f399f Gerrit-PatchSet: 1 Gerrit-Project: asterixdb Gerrit-Branch: master Gerrit-Owner: Till Westmann <ti...@apache.org> Gerrit-Reviewer: Jenkins <jenk...@fulliautomatix.ics.uci.edu> Gerrit-Reviewer: Jianfeng Jia <jianfeng....@gmail.com> Gerrit-Reviewer: Michael Carey <dtab...@gmail.com> Gerrit-Reviewer: Till Westmann <ti...@apache.org> Gerrit-Reviewer: Xikui Wang <xkk...@gmail.com> Gerrit-HasComments: Yes
