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 <[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/> >> >> >> > > _______________________________________________ > Architecture mailing list > [email protected] > https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture > > -- Regards, Uvindra Mobile: 777733962
_______________________________________________ Architecture mailing list [email protected] https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
