Hi Frank, By doing this I don't think we're sacrificing consumability of the API. Except for the fact that we're expecting users to send the minor version in an http header (which we could make optional too).
With the continuous integration and continuos delivery model, I'm assuming we will be introducing newer minor versions of the API at a higher rate than we used to. So say we have v1.0, v1.1 and v1.2 of the API. On the latest product version, we're bound to support all if not most of these versions. To support each of these versions we need to maintain different copies of the source code and need to host an app (or service) each on the server runtime. Which is a significant overhead. And if we do a bug fix in version v1.0, we need to replicate that fix on the rest of the versions while ensuring backward compatibility. So IMO yes, this reduces our development complexity significantly. To answer the question of whether we're ready to commit to this, I personally don't see this as committing to something entirely new. Say someone is using version v1.0, the reason he'd probably want to switch to v1.1 is to use a new feature we introduced. That still means his current code has to work with v1.1 exactly as it used to do in v1.0. I think we've already committed ourselves to supporting that :) Thanks, NuwanD. On Thu, Nov 17, 2016 at 8:21 PM, Frank Leymann <[email protected]> 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 <[email protected]>: > >> +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 <[email protected] >> > 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 <[email protected]> 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 <[email protected]> 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 : [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>* >>>> >>>> >>> >>> >>> -- >>> 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/> >> >> >> > -- Nuwan Dias Software Architect - WSO2, Inc. http://wso2.com email : [email protected] Phone : +94 777 775 729
_______________________________________________ Architecture mailing list [email protected] https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
