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
