Hi Abimaran,
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?
Yes, we are not changing request or response in same major version. The
"Minor-Version" header is optional. It will point to default minimum minor
version if not specified.
@ApiParam(value = "Validator for API Minor Version " ,
defaultValue="1.0")@HeaderParam("Minor-Version") String minorVersion
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?
>
> 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 <+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
>
>
--
*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
