Hi All, How are we going to differentiate when to have the new minor version and when to create 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? 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 <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
