RE: [cxs] Another productive Workgroup 3 session

[Kaloyan Nikolov <Kaloyan.Nikolov@telerik.com>]

Hi guys,

 

My comments are here:

 

1.       GET with body vs. POST

·         POST is not cache-able by the browser which means that those queries will be executed each time. In some cases we would like to cache them for short period but there will be no possibility for this using POST

·         The only API I know for using GET wit body is ElasticSearch, should we base our API on this I would say “Exception”? Furthermore I see in the internet some articles saying that there are servers and clients having issues with body for GET.

2.       About dynamic JSON structures like {… and: [… ] }, as Chris pointed out the property keys are not known and when you parse it you should check if any of the supported are present in the JSON object. Another issue is that the more typed languages like C# might struggle a bit to serialize/deserialize such objects.

 

Kaloyan.

 

From: cxs@lists.oasis-open.org [mailto:cxs@lists.oasis-open.org] On Behalf Of Christophe Laprun
Sent: Thursday, June 23, 2016 10:59 PM
To: Thomas Sigdestad <tsi@enonic.com>
Cc: Serge Huber <shuber@jahia.com>; cxs@lists.oasis-open.org
Subject: Re: [cxs] Another productive Workgroup 3 session

 

Hi all,

 

My comments, inlined.

 

On 23 Jun 2016, at 17:38, Thomas Sigdestad <tsi@enonic.com> wrote:

 

Hi all!

 

Workgroup 2 just had a _very_ productive meeting (after som postponed ones) :-)

Interesting stuff to see from WG3 - and especially liked Serge’s touch at the end there! It seems brilliant. We have attempted to apply this in our work too.

 

While we’re at it we propose an even simpler DSL for the query, why not simply drop the whole “function” and “arguments” thing and just go for a function:[args] pattern?

 

{

 

     and:[{

 

          geoDistance:[{

 

              geoLocation : 'x',

 

              distance : 'y', }]

 

          },

 

          {

 

          in:[1,2,3]

 

      }]

} 

 

I thought about that option as well. However, the problem with this is that you don’t know the keys in advance which makes it more difficult to process the JSON object. On the hand, while the other solution is more verbose, it is also clearer as to the purpose of each elements in the structure and they can always be retrieved by their known keys.

‌‌This is basically the same, but leaner syntax!

BTW: Using functions to create the entire query language is supposedly used elsewhere too :-). I will try to get some links

 

 

Also, we have opinions on the following:

* We should not use POST for queries but GET, as this is much more obvious - cleanly using POST to create and GET to, well get data.

 

Regarding this issue, which we already addressed previously, I’ll re-post the information I posted previously on the subject: 

Another issue was whether to use POST or GET methods for queries in the endpoint. We settled on using POST which, after consideration make sense (if your resource is “queries” then, POST with data allows you to “create” a query).

 

Here are some links on the issue:

https://evertpot.com/dropbox-post-api/ (this one mentions the REPORT method which I wasn’t aware of)

Roy Fielding’s point of view on the question (via SO): http://stackoverflow.com/a/983458

 

* We think the complex stuff (query, sorting?) modelled as JSON should be sent in the body (this is how Elasticsearch does it, and it looks nice)

 

Agreed, however, not with a GET method… ;)

* Simple parameters such as offset, pageSize and maybe parameters to return should be plainly sent in the querystring, so one can easily access data even without using the body parameter and complex JSON stuff?

 

I’d rather have all the request parameters in the same spot. So if we have a body, I’d prefer have all the parameters in the body instead of some in the URL and some in the body. However, if we are using the URL for parameters, we should strive to put all the parameters there as well and not use a body.

 

Check out the swagger file for the /events/ api endpoint. (sorry, just committed, no pull req this time!)

 

Finally - we are very skeptical of a generic /query endpoint - we prefer that each endpoint (events/ profiles/ etc) rather enable passing a query object to them - so you will never have to worry about what will be returned and how to make it work.

 

The idea of a generic query endpoint was to be able to do queries across object domains (e.g. joins) but it would be useless to have such an endpoint and not fully specify the query language and the expected results. We can probably try to do without initially.

 

Cheers!

 

Christophe Laprun
Senior Software Engineer

8 rue du Sentier | 75002 Paris | France

jahia.com

SKYPE | LINKEDIN | TWITTER | VCARD

 

> JOIN OUR COMMUNITY to evaluate, get trained and to discover why Jahia is a leading User Experience Platform (UXP) for Digital Transformation.