Hi all, I think it is important to deviate from the swagger specification only in respects to making the URI verification more like what our customers expect. More natural, more intuitive. Intuitively, the URI mapping should cover the URI, but query parameters are IMO, separate from the URI. I am +1 for allowing query parameters as optional, and not needing to define resources with *. There are many valid cases where adding the * for query parameters can mess up an otherwise good URI scheme. For example, one customer wanted to have use the following URIs:
1. GET http://domain:port/context/1.0.0/orders?region="US"; 2. GET http://domain:port/context/1.0.0/orders/orderid/123456 IMO, this seems like a valid, well ordered scheme, but we can't support it. the option 1 requires a resource with /orders* and the option 2 requires a resource with /orders/orderid/{orderNumber}. If we removed the necessity for the * in a resource, it woudl allow optional query parameters. We would need to change our validation code to ignore query parameters during URI template validation. Besides, having * for URI validation is messy, and should be avoided in general. It does not adequately describe a resource, so it makes the swagger documentation less useful. We should specify each query parmaeter individually anyway, and validate against the query parameters we define. So, in general, I'm for going with teh swagger definitions, but we should not be constrained by them. In particular, we should not force the * to be used in a resource template when there are query parameters. Cheers, Colin Roy-Ehri Software Engineer *WSO2, Inc. : wso2.com <http://wso2.com/>* *Mobile* : 812-219-6517 On Fri, Oct 23, 2015 at 2:27 AM, Sanjeewa Malalgoda <[email protected]> wrote: > > > On Fri, Oct 23, 2015 at 11:03 AM, Joseph Fonseka <[email protected]> wrote: > >> Hi Sanjeewa >> >> On Thu, Oct 22, 2015 at 1:47 PM, Sanjeewa Malalgoda <[email protected]> >> wrote: >>> >>> >>> Other important thing we should focus is define resources which do not >>> accept query parameters. >>> >> >> What would be a use case for this ? Usually in APIs we simply ignore the >> additional query parameters. >> > Some scenarios we don't want to have query parameters. > Some of users use this pattern to avoid lengthy urls and malformed urls. > They basically want to get only matching requests in. > As per spec those are optional and client can decide sending them or not. > >> >> >> >>> And other important usage of * is create APIs for services which does >>> not implemented completely. >>> As example we can have this kind of resource >>> >>> /bookStore/{bookID}* >>> >>> In future backend service implementation may have >>> /bookStore/{bookID}/move >>> /bookStore/{bookID}/transfer >>> etc. >>> >>> So its not necessary query parameters but those are control verbs in >>> resource path(no query parameters). >>> So we may need to focus on that aspect as well. >>> >> >> Above use case can be handled by using "/bookStore/{bookID}{/paths*}" >> which will qualify above paths see [1]. >> > if it supports both having control verbs and not having them its good i > think. So we may go for that. > i think following will support with that > /bookStore/123 GET > /bookStore/123/move POST > > > > Thanks, > sanjeewa. > > >> >> Thanks >> Jo >> >> >> [1] https://tools.ietf.org/html/rfc6570#section-3.2.6 >> >> >> >> >>> >>> Thanks, >>> sanjeewa. >>> >>> On Thu, Oct 22, 2015 at 12:00 PM, Joseph Fonseka <[email protected]> >>> wrote: >>> >>>> >>>> >>>>> Do you think we can migrate Resources of APIs which have been defined >>>>> with * without breaking existing clients? >>>>> >>>> >>>> For API manager it is possible but this affects the existing ESB users >>>> as well for them it would be a manual migration. >>>> >>>> 4. Support full URI Templates in ESB and only support what is supported >>>>>> in swagger in API Manager. >>>>>> >>>>> >>>>> I don't think it's a good idea to limit ourselves to what swagger >>>>> supports. >>>>> >>>> >>>> Yes that make sense going forward swagger might adopt the URI >>>> Templating. If so we have following two options. >>>> 1. Do nothing and clearly inform users if unsupported URITemplate is >>>> used it will not work properly with swagger console. >>>> 2. Use swagger vendor extension to give support to unsupported url >>>> template. >>>> Ex. In swagger we can use an attribute like "x-uri-template" >>>> under a resource which will be used to create the resource in synapse. >>>> >>>> Regards >>>> Jo >>>> >>>> >>>> >>>>> *Joseph Fonseka* >>>>>> WSO2 Inc.; http://wso2.com >>>>>> lean.enterprise.middleware >>>>>> >>>>>> mobile: +94 772 512 430 >>>>>> skype: jpfonseka >>>>>> >>>>>> * <http://lk.linkedin.com/in/rumeshbandara>* >>>>>> >>>>>> >>>>> >>>>> -- >>>>> Nuwan Dias >>>>> >>>>> Technical Lead - WSO2, Inc. http://wso2.com >>>>> email : [email protected] >>>>> Phone : +94 777 775 729 >>>>> >>>>> >>>> >>>> >>>> -- >>>> >>>> -- >>>> *Joseph Fonseka* >>>> WSO2 Inc.; http://wso2.com >>>> lean.enterprise.middleware >>>> >>>> mobile: +94 772 512 430 >>>> skype: jpfonseka >>>> >>>> * <http://lk.linkedin.com/in/rumeshbandara>* >>>> >>>> >>>> _______________________________________________ >>>> Architecture mailing list >>>> [email protected] >>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>> >>>> >>> >>> >>> -- >>> >>> *Sanjeewa Malalgoda* >>> WSO2 Inc. >>> Mobile : +94713068779 >>> >>> <http://sanjeewamalalgoda.blogspot.com/>blog >>> :http://sanjeewamalalgoda.blogspot.com/ >>> <http://sanjeewamalalgoda.blogspot.com/> >>> >>> >>> >>> _______________________________________________ >>> Architecture mailing list >>> [email protected] >>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>> >>> >> >> >> -- >> >> -- >> *Joseph Fonseka* >> WSO2 Inc.; http://wso2.com >> lean.enterprise.middleware >> >> mobile: +94 772 512 430 >> skype: jpfonseka >> >> * <http://lk.linkedin.com/in/rumeshbandara>* >> >> >> _______________________________________________ >> Architecture mailing list >> [email protected] >> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >> >> > > > -- > > *Sanjeewa Malalgoda* > WSO2 Inc. > Mobile : +94713068779 > > <http://sanjeewamalalgoda.blogspot.com/>blog > :http://sanjeewamalalgoda.blogspot.com/ > <http://sanjeewamalalgoda.blogspot.com/> > > > > _______________________________________________ > Architecture mailing list > [email protected] > https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture > >
_______________________________________________ Architecture mailing list [email protected] https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
