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]
_______________________________________________
Architecture mailing list
[email protected]
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
