But, if we use minor version, we have to maintain separate methods/separate
if checks to populate response for each minor versions. But, if we have
optional parameters, then no need to have separate methods, if an optional
parameter is there in the request, we can add a relevant response.
If we keep minor version, then we have to maintain a documentation on which
functionality was added to which minor version and source code also will be
messy.
On Wed, Feb 8, 2017 at 5:00 PM, Nuwan Dias <nuw...@wso2.com> wrote:
>
>
> On Wed, Feb 8, 2017 at 4:15 PM, Abimaran Kugathasan <abima...@wso2.com>
> 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 <
>> anurudd...@wso2.com> 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 <malint...@wso2.com
>>> > 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 <
>>>> anurudd...@wso2.com> 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 <
>>>>> anurudd...@wso2.com> 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 <
>>>>>> jochen.traunec...@googlemail.com> 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 <jochen.traunec...@googlemail.com> 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 <uvin...@wso2.com> 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 <fr...@wso2.com> 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 <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
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>> Regards,
>>>>>>>> Uvindra
>>>>>>>>
>>>>>>>> Mobile: 777733962
>>>>>>>> _______________________________________________
>>>>>>>> Architecture mailing list
>>>>>>>> Architecture@wso2.org
>>>>>>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>>>>>>>
>>>>>>>>
>>>>>>> _______________________________________________
>>>>>>> Architecture mailing list
>>>>>>> Architecture@wso2.org
>>>>>>> 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 <thili...@wso2.com>nurudd...@wso2.com
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> *Thanks and Regards,*
>>>>> Anuruddha Lanka Liyanarachchi
>>>>> Software Engineer - WSO2
>>>>> Mobile : +94 (0) 712762611
>>>>> Tel : +94 112 145 345
>>>>> a <thili...@wso2.com>nurudd...@wso2.com
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> 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 <thili...@wso2.com>nurudd...@wso2.com
>>>
>>> _______________________________________________
>>> Architecture mailing list
>>> Architecture@wso2.org
>>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>>
>>>
>>
>>
>> --
>> Thanks
>> Abimaran Kugathasan
>> Senior Software Engineer - API Technologies
>>
>> Email : abima...@wso2.com
>> 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
>> Architecture@wso2.org
>> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>>
>>
>
>
> --
> Nuwan Dias
>
> Software Architect - WSO2, Inc. http://wso2.com
> email : nuw...@wso2.com
> Phone : +94 777 775 729 <+94%2077%20777%205729>
>
> _______________________________________________
> Architecture mailing list
> Architecture@wso2.org
> https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
>
>
--
Thanks
Abimaran Kugathasan
Senior Software Engineer - API Technologies
Email : abima...@wso2.com
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
Architecture@wso2.org
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
