On Wed, Feb 8, 2017 at 4:15 PM, Abimaran Kugathasan <[email protected]> wrote:
> Hi All, > > How are we going to differentiate when to have the new minor version and > when to create new major version? > If we're doing a back-wards incompatible change then it has to be on a new major version. > > I guess, within the same Major version range, we can't change mandatory > request parameters and response parameters. So, without using minor > versions, can't use optional parameters to the APIs? > The version also matter for responses. If we decide to enhance the response payload in a backwards compatible way, we have to do it explicitly by knowing the client is using the newer minor version. > > On Wed, Feb 8, 2017 at 4:02 PM, Anuruddha Liyanarachchi < > [email protected]> wrote: > >> Hi Malintha, >> >> We are defining the Minor-Version header in the parameters section and >>> then including the reference of the Minor-Version parameter using ($ref) in >>> the methods we need explicitly right? >> >> >> Yes. We are defining it in the parameter section and adding it using $ref >> for all the methods. >> >> On Wed, Feb 8, 2017 at 3:57 PM, Malintha Amarasinghe <[email protected]> >> wrote: >> >>> Hi Anuruddha, >>> >>> We are defining the Minor-Version header in the parameters section and >>> then including the reference of the Minor-Version parameter using ($ref) in >>> the methods we need explicitly right? >>> >>> Since we do not need to support minor version in every resource, it is >>> fine to handle it specifically in each method as you have suggested IMO. +1 >>> from me for this way. >>> >>> Thanks! >>> Malintha >>> >>> On Wed, Feb 8, 2017 at 3:41 PM, Anuruddha Liyanarachchi < >>> [email protected]> wrote: >>> >>>> Hi, >>>> >>>> I am planning to implement the minor version header functionality. >>>> Please find below the implementation details. >>>> >>>> Appreciate your feedback on this approach. >>>> >>>> 1. The custom HTTP header will look like below: >>>> >>>> # The HTTP Minor-Version header >>>> # Used to validate the minor version of API >>>> Minor-Version: >>>> name: Minor-Version >>>> in: header >>>> description: >>>> Validator for API Minor Version >>>> type: string >>>> default: 1.0 >>>> >>>> >>>> 2.The major version will be v1, and sample path will be look like below: >>>> >>>> /api/am/admin/v1/policies >>>> >>>> >>>> 3. Each resource will have a parameter to get minor version and default >>>> value will be 1.0. >>>> >>>> @ApiParam(value = "Validator for API Minor Version " , >>>> defaultValue="1.0")@HeaderParam("Minor-Version") String minorVersion >>>> >>>> >>>> 4. In the implementation minorVersion parameter can be used to change the >>>> implementations conditionally. >>>> >>>> @Override >>>> public Response policiesTierLevelGet(String tierLevel, Integer limit, >>>> Integer offset, String accept, String ifNoneMatch, >>>> String minorVersion) throws >>>> NotFoundException { >>>> // major version implementation >>>> >>>> >>>> if (Integer.parseInt(minorVersion) > 1) { >>>> // new logic >>>> } >>>> return Response.ok().entity(new >>>> ApiResponseMessage(ApiResponseMessage.OK, "Sucess!")).build(); >>>> } >>>> >>>> >>>> >>>> On Wed, Feb 8, 2017 at 12:23 PM, Anuruddha Liyanarachchi < >>>> [email protected]> wrote: >>>> >>>>> Hi, >>>>> >>>>> 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 >>>>> >>>>> >>>>> Supporting multiple version in URL is having different implementations >>>>> under different context paths. Isn't it what we are trying to avoid at the >>>>> first place using custom minor version header? >>>>> >>>>> /someresource/v1/thisandthat -> default version, always latest >>>>>> greatest minor version within v1, with optional header >>>>> >>>>> Shouldn't we support the minimum minor version if the header is not >>>>> specified? >>>>> This way, the client only need to send the header if latest update is >>>>> required. >>>>> >>>>> Regards, >>>>> Anuruddha >>>>> >>>>> On Thu, Nov 17, 2016 at 9:49 PM, Jochen Traunecker < >>>>> [email protected]> wrote: >>>>> >>>>>> 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 <[email protected]> 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 <[email protected]> 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 <[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-api >>>>>>> s-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 >>>>>>> >>>>>>> >>>>>> _______________________________________________ >>>>>> Architecture mailing list >>>>>> [email protected] >>>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >>>>>> >>>>>> >>>>> >>>>> >>>>> -- >>>>> *Thanks and Regards,* >>>>> Anuruddha Lanka Liyanarachchi >>>>> Software Engineer - WSO2 >>>>> Mobile : +94 (0) 712762611 >>>>> Tel : +94 112 145 345 >>>>> a <[email protected]>[email protected] >>>>> >>>> >>>> >>>> >>>> -- >>>> *Thanks and Regards,* >>>> Anuruddha Lanka Liyanarachchi >>>> Software Engineer - WSO2 >>>> Mobile : +94 (0) 712762611 >>>> Tel : +94 112 145 345 >>>> a <[email protected]>[email protected] >>>> >>> >>> >>> >>> -- >>> Malintha Amarasinghe >>> Software Engineer >>> *WSO2, Inc. - lean | enterprise | middleware* >>> http://wso2.com/ >>> >>> Mobile : +94 712383306 <+94%2071%20238%203306> >>> >> >> >> >> -- >> *Thanks and Regards,* >> Anuruddha Lanka Liyanarachchi >> Software Engineer - WSO2 >> Mobile : +94 (0) 712762611 >> Tel : +94 112 145 345 >> a <[email protected]>[email protected] >> >> _______________________________________________ >> Architecture mailing list >> [email protected] >> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture >> >> > > > -- > Thanks > Abimaran Kugathasan > Senior Software Engineer - API Technologies > > Email : [email protected] > Mobile : +94 773922820 <+94%2077%20392%202820> > > <http://stackoverflow.com/users/515034> > <http://lk.linkedin.com/in/abimaran> > <http://www.lkabimaran.blogspot.com/> <https://github.com/abimarank> > <https://twitter.com/abimaran> > > > _______________________________________________ > Architecture mailing list > [email protected] > https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture > > -- 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
