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