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
