Hi again, Assuming these policies are in place: P1: minor versions guarantee backward compatibility P2: major version can break backward compatibility
You could offer clients a URI only approach and header approach in parallel like this: /someresource/v1/thisandthat -> default version, always latest greatest minor version within v1, with optional header pointing to specific version /someresource/v11/thisandthat /someresource/v12/thisandthat /someresource/v2/whatever -> default version /someresource/v21/whatever Cheers Jochen Jochen Traunecker <jochen.traunec...@googlemail.com> schrieb am Do. 17. Nov. 2016 um 16:52: > Hi,, > > From a consumer's perspective there should be no mandatory minor version > header enforced. Sticking to Frank's policies about compatibility within > major/minor versions there would be no need to touch any client code when > consuming APIs that just got a minor upgrade. Especially in strict > regulated environments (e.g. Financial industry) it could help reduce the > effort to upgrade middleware components as only testing of consumers is > mandatory and not on top of that "changing" consumer code. > > Thanks! > > Jochen > > Uvindra Dias Jayasinha <uvin...@wso2.com> schrieb am Do. 17. Nov. 2016 um > 16:33: > > I think there is agreement that we can go with just the major version as > part of the URI, but I'm still wondering if we need to ask users to send > the minor version in a header. > > Users can mistakenly send a wrong minor version and if we blindly take > decisions based on that header it could lead to errors. So we anyway need > to do a sanity check to make sure the optional parameter introduced in a > given minor version has been populated by the user as expected. So now > users need to send an additional minor version but we cant really trust > that because there is no guarantee that the parameters will be compatible. > > So seems like the minor version in the header is an unwanted overhead for > both the user and us. > > I can understand us needing to support multiple major versions but not > multiple minor versions. So we will only have the latest minor version > implementation that is fully backward compatible to its respective major > version and preceding minor versions. > > > On 17 November 2016 at 20:21, Frank Leymann <fr...@wso2.com> wrote: > > We need to discuss this more carefully. > > The real question is: *do we want to make it easy for us, or do we want > to make it easy for our customers? *I think that we should strive for > APIs that serve our customers as simple as possible. And this means that > clients must not break. > > Nearly all > know > n > REST APIs use URI-based versioning (see section "Versioning strategies in > popular REST APIs" > at > http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/). > Out of the other approaches, Azure is using a proprietary header (which is > not RESTful because it significantly reduces "visibility") and GitHub > recently switched to HTTP Accept headers. > > Thus, we should stick to our decision to support URI-based versioning. > Having said that, t > he URI-based versioning camp is split into specifying both, major and > minor version, and only specifying major version. Facebook, Netflix,... are > supporting major/minor. > > If it reduces our development effort significantly, and if we guarantee > (!) that minor versions are backward compatible (which they are by the very > definition), then using major versions only maybe fine (Jo says the same). > Remember that backward compatibility means that we are only allowed to add > optional (!) new parameters in the API, that we do not return payload that > the client doesn't understand/can parse, that we do not return new status > codes etc etc. All of that requires a new major version. Are we ready to > commit to this? > > > > > Best regards, > Frank > > 2016-11-17 11:25 GMT+01:00 Sanjeewa Malalgoda <sanje...@wso2.com>: > > +1. I have some doubts about using minor versions within the > implementation. If we don't have multiple apps(jax-rs apps or micro > services) then single app should handle all minor version requests and > process accordingly. Then we may need to have multiple methods in java > API(for each minor version) and call them accordingly from REST API. > Or we need to have single method in java API and implement processing > logic based on minor version. WDYT? > > Thanks, > sanjeewa. > > On Thu, Nov 17, 2016 at 2:38 PM, Malintha Amarasinghe <malint...@wso2.com> > wrote: > > Hi, > > +1 for the approach since it give many benefits and simplifications. > > However, if we remove version, shouldn't there be some way that client can > know the version of the API he is going to call. > For example: in v1.0 there is /sample resource that does some work. And in > v1.1, there is /sample-2 resource that does the same work but in a better > way. So someone wants to write a code that calls the correct resource as > per the version of the API he is calling. > As Nuwan/Jo mentioned client sending minor version as a header, shouldn't > server also send the minor version of the API to the client (may be as a > header or some other way) to support the above case? > > Thanks! > Malintha > > > > > > > > On Thu, Nov 17, 2016 at 2:24 PM, Joseph Fonseka <jos...@wso2.com> wrote: > > Hi Nuwan > > +1 for the approach. I think this will simplify on how we support multiple > versions on server side. If we adopt it we may only have to ship an > implementation for each major version. > > If we can ensure forward compatibility I guess there will be no issue with > this approach otherwise we will see the clients breaking if they try to > access an previous minor version of the same API. > > To solve the later case we can mandate clients should send the minor > version they are intend to use with the request ( may be in a header ) so > that server can validate and send a error if that is not supported. > > Furthermore will it make sense to have the full version of the API in the > header ? > > Thanks & Regards > Jo > > > [1] http://wso2.com/whitepapers/wso2-rest-apis-design-guidelines/ > > > > > > On Thu, Nov 17, 2016 at 1:50 PM, Nuwan Dias <nuw...@wso2.com> wrote: > > Hi, > > The API Manager REST API [1], [2] follows the semantic versioning > strategy. It currently requires you to have the Major.Minor versions in the > URI scheme (/api/am/publisher/v*0.10*). This however is problematic > because practically, as we add features to the product we need to add new > resources to the API (backwards compatible API changes) and hence have to > change the .Minor version of it on every new release. > > This results in complications because we have to keep supporting at least > a few .Minor versions backward on a given product version (support for > v1.0, v1.1, v1.2). Which means that we have to ship and maintain several > versions of the JAX-RS (or Microservice) at any given time. > > Shall we adopt a strategy where we only mandate the .Major version in the > URI scheme (/api/am/publisher/v*1*/) and request for the .Minor version > to be sent as a Header? This will ensure that we don't have to maintain > several versions of the JAX-RS on a given server runtime and if we need the > .Minor version for some functionality we look it up from the Header. > > [1] - https://docs.wso2.com/display/AM200/apidocs/publisher/ > [2] - https://docs.wso2.com/display/AM200/apidocs/store/ > > Thanks, > NuwanD. > > -- > Nuwan Dias > > Software Architect - WSO2, Inc. http://wso2.com > email : nuw...@wso2.com > 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>* > > > > > -- > Malintha Amarasinghe > Software Engineer > *WSO2, Inc. - lean | enterprise | middleware* > http://wso2.com/ > > Mobile : +94 712383306 > > > > > -- > > *Sanjeewa Malalgoda* > WSO2 Inc. > Mobile : +94713068779 > > <http://sanjeewamalalgoda.blogspot.com/>blog > :http://sanjeewamalalgoda.blogspot.com/ > <http://sanjeewamalalgoda.blogspot.com/> > > > > > _______________________________________________ > Architecture mailing list > Architecture@wso2.org > https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture > > > > > -- > Regards, > Uvindra > > Mobile: 777733962 > _______________________________________________ > Architecture mailing list > Architecture@wso2.org > https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture > >
_______________________________________________ Architecture mailing list Architecture@wso2.org https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
