Let's consider we have the following APIs /twitter/ /twitter/1.0.0 /twitter/2.0.0
When a request is made as http://host:port/twitter/1.0.0, there is no guarantee whether it is /twitter or /twitter/1.0.0 that is being invoked. Since the *isMatchingVersion* function in RESTRequestHandler always returns true for /twitter, if /twitter stands higher in the list, it will be matched and invoked. To avoid this, we will be reordering the api list so that /twitter gets the last position of the list. Therefore /twitter will only be invoked if there is no matching version found. The following limitations apply when we're having an API as a default version API a) Once you define a default version API, it remains final and cannot change. This means that you cannot go and assign a version to it on a later day. The reason for this is because it will cause client applications to fail since you are changing the contract. b) The above would mean that if you already have a default version API, you cannot mark a new API as a default version API. This sounds fair enough to me because you are trying to expose a new contract over an old interface and this would again cause old apps to break. Thanks, NuwanD. On Fri, Mar 14, 2014 at 3:21 PM, Malintha Amarasinghe <malint...@wso2.com>wrote: > Hi All, > > When exposing APIs, API Manager uses existing synapse core, which is > already used in WSO2 ESB. Because of that, the behavior of APIs which does > not having version attributes can be tested by defining similar APIs in > synapse configuration in an ESB instance. > > *The problem in synapse currently* > > Accordingly, I defined a set of APIs with the same name and the context > with one of them without having any version related attributes(*version* > or *version-type*). Then following was observed by testing their > behavior, invoking them using curl. > > 1) If I invoke without using a version (say > http://host:port*/*twitter/search), > then it is correctly handled by the API having no version. > > 2) Keeping the same synapse configuration, if I invoke APIs which has a > version (say http://host:port*/*twitter/1.0.0/search), then "some" of the > versions seems also pass into the API with no version. > > 3) If I invoke some API version which does not exist in the synapse > configuration, then it also passes into the API with no version. > > Since the above 2) is unexpected, I explored some parts of the synapse > core and found the following. > > > *Background:* > > 1) When a message arrives to call an API, RESTRequestHandler(in > org.apache.synapse.rest) gets the current list of APIs and process one by > one to find whose version matches with the version in the message.* It > will handle the message to the first found API which matches the version. * > > 2) In an API, getting and comparing versions is done through an interface > called VersionStrategy(in org.apache.synapse.rest.version). There are two > classes which implements it, which are DefaultStrategy > and URLBasedVersionStrategy. > > 3) When an API is created, initially it is mapped to DefaultStrategy. But > when we specify *version-type *attribute as "url" ( <api name="TestAPI" > ... .. *version-type="url"*> ) VersionStrategy will be mapped into > URLBasedVersionStrategy. > > 4) There is a method called *isMatchingVersion(Object versionInfoObj)* in > VersionStrategy to check whether an API's version matches with the > *versionInfoObj'*s version (into which the version of the current message > is passed) > > *Cause for the problem:* > > 5) There is a logic implemented in *isMatchingVersion() *in the > implementation of URLBasedVersionStrategy. *But in DefaultStrategy, there > is no logic and **isMatchingVersion(**versionInfoObj**)** always return > true for whatever we pass into **versionInfoObj. * > > 6) If we create an API without specifying the *version-type *attribute, > VersionStrategy stay remains in DefaultStrategy( as pointed in 3. ) and if > the related API stays in a higher position in the list of APIs, it will get > selected as soon as RESTRequestHandler reaches it in the list of APIs. As I > found, that is the reason for it to get selected inappropriately. > > *Options to consider:* > > Following are some options which can be considered to solve this. > > 1) When creating an API, avoiding both *version* and *version-type > *attributes, > and then fix the code to avoid happening 5) and 6). > > 2) Keeping everything as it is, and specifying some kind of string to the > version attribute, such as *version="latest". *But it is not a > conventional way and also not well-suited for the current goal. > > Please share your ideas as well. > > Thank you. > > Regards, > Malintha Amarasinghe, > Engineering Intern. > > > On Thu, Mar 13, 2014 at 12:23 PM, Nuwan Dias <nuw...@wso2.com> wrote: > >> On Thu, Mar 13, 2014 at 11:57 AM, Samisa Abeysinghe <sam...@wso2.com>wrote: >> >>> So défault URL defaults to the latest API version available? >>> >> >> The default url (/twitter) always invokes the default version API (this >> may or may not be the latest). If the API creator maintains the latest >> version as the default version, then the above said is true. >> >>> >>> And we allow users to configure what API version is default, in case >>> latest is not the greatest? >>> >> >> Yes. >> >>> >>> Thanks, >>> Samisa... >>> >>> >>> Samisa Abeysinghe >>> >>> Vice President Developer Evangelism >>> >>> WSO2 Inc. >>> http://wso2.com >>> >>> >>> >>> On Thu, Mar 13, 2014 at 11:31 AM, Nuwan Dias <nuw...@wso2.com> wrote: >>> >>>> Hi, >>>> >>>> All APIs currently being created on the API Manager require a version >>>> attribute to be present. This version is required to be present in the API >>>> invocation url following the API context. For example if there is an API >>>> such that its context=/twitter, version=1.0.0 and resource=/search, the API >>>> invocation url will be similar to >>>> >>>> http://host:port*/twitter/1.0.0*/search >>>> >>>> Given an API with several versions, this discussion is to allow 1 API >>>> out of the group to exist without a version. This API will be referred to >>>> as the 'default' version API. >>>> >>>> So if there are APIs as /twitter/1.0.0, /twitter/2.0.0, etc. It will be >>>> allowed to have 1 API as /twitter. Whenever a user attempts to access an >>>> API without the version value in the url, the default API version will be >>>> invoked. >>>> >>>> The Publisher UI should be tweaked in such a way that it will remove >>>> the mandatory nature of the version field and make the user either provide >>>> a version or mark the API as the default version API. Necessary checks need >>>> to be done to ensure that there cannot be two default versions of the same >>>> API and the same checks need to run when copying APIs as well. >>>> >>>> Thanks, >>>> NuwanD. >>>> >>>> -- >>>> Nuwan Dias >>>> >>>> Senior Software Engineer - WSO2, Inc. http://wso2.com >>>> email : nuw...@wso2.com >>>> Phone : +94 777 775 729 >>>> >>>> _______________________________________________ >>>> 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 >>> >>> >> >> >> -- >> Nuwan Dias >> >> Senior Software Engineer - WSO2, Inc. http://wso2.com >> email : nuw...@wso2.com >> Phone : +94 777 775 729 >> >> _______________________________________________ >> 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 > > -- Nuwan Dias Senior Software Engineer - WSO2, Inc. http://wso2.com email : nuw...@wso2.com Phone : +94 777 775 729
_______________________________________________ Architecture mailing list Architecture@wso2.org https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
