Return-Path: X-Original-To: apmail-airavata-dev-archive@www.apache.org Delivered-To: apmail-airavata-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 594A710C63 for ; Thu, 8 Aug 2013 17:34:24 +0000 (UTC) Received: (qmail 78498 invoked by uid 500); 8 Aug 2013 17:34:23 -0000 Delivered-To: apmail-airavata-dev-archive@airavata.apache.org Received: (qmail 78380 invoked by uid 500); 8 Aug 2013 17:34:22 -0000 Mailing-List: contact dev-help@airavata.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@airavata.apache.org Delivered-To: mailing list dev@airavata.apache.org Delivered-To: moderator for dev@airavata.apache.org Received: (qmail 74763 invoked by uid 99); 8 Aug 2013 17:33:30 -0000 X-ASF-Spam-Status: No, hits=-0.7 required=5.0 tests=RCVD_IN_DNSWL_LOW,SPF_HELO_PASS,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: domain of dooley@tacc.utexas.edu designates 146.6.25.7 as permitted sender) X-Utexas-Sender-Group: RELAYLIST-AEMS X-IronPort-MID: 281050002 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AiYFAJ3VA1KsEEdW/2dsb2JhbABbgwY1UL5JgRoWdIIkAQEBBHkQAgEFAw4DBAEBAQodByERFAkIAgQOBQiHdgMPDLA3DQdQiAeNK4EqgRUxB4MadAOFDZBrgxOCWYYxgXSFJ4MYPIEsCRcDHw X-IronPort-AV: E=Sophos;i="4.89,840,1367989200"; d="scan'208";a="281050002" X-Utexas-Seen-Outbound: true From: Rion Dooley To: Suresh Marru CC: "dev@airavata.apache.org" Subject: RE: Changing the registry rest service context & url Thread-Topic: Changing the registry rest service context & url Thread-Index: AQHOlFOtiDI+Xs3zK0K/5ax9qQ2/U5mLj/3p Date: Thu, 8 Aug 2013 17:33:02 +0000 Message-ID: <438B6EDA761A1D4EBF8F3C08C967C4C935DC522F@EXMBX01.austin.utexas.edu> References: ,<1E06A263-FAF2-4329-A04A-4B81EA14C419@apache.org> In-Reply-To: <1E06A263-FAF2-4329-A04A-4B81EA14C419@apache.org> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-originating-ip: [198.85.51.234] Content-Type: text/plain; charset="Windows-1252" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Virus-Checked: Checked by ClamAV on apache.org Short answer is I would add v2 to the url.=0A= =0A= The long answer is that my thinking on this changed recently. I used to thi= nk that a constant URL structure with the version included in the content t= ype or response objects was preferable, but for practical purposes, unless = your API structure is fixed and you don't ever see it changing, it's actual= ly harder on your clients to deal with a constant url that one with the ver= sion in the URL. The reason being that when you upgrade the primary API, th= eir stuff breaks and because they were ignoring their emails, or don't have= money to support their software anymore, they don't know why. By including= the version in your url, it's obvious which one you're using and when you = deprecate a version, they get a 404 rather than some cryptic 500 or 600 err= ors. Another thing I've found is that people like REST because it's pretty = easy to interact with. When you start asking them to mess with custom heade= rs and the Content-Type, you're adding complexity when what you want to do = is remove it. =0A= =0A= All of this is my opinion. There isn't any law that says one over the other= and, as I stated earlier, my opinion has changed after building a couple a= pis and dealing with versioning issues over time. YOu might want to join th= e api-craft google group to read some other opinions. https://groups.google= .com/forum/#!forum/api-craft=0A= =0A= =0A= Rion=0A= ________________________________________=0A= From: Suresh Marru [smarru@apache.org]=0A= Sent: Thursday, August 08, 2013 11:23 AM=0A= To: dev@airavata.apache.org=0A= Cc: Rion Dooley=0A= Subject: Re: Changing the registry rest service context & url=0A= =0A= Hi Rion,=0A= =0A= We will appreciate your advises on API Naming conventions based on your exp= eriences with Foundation API - https://foundation.iplantcollaborative.org/= =0A= =0A= Thanks,=0A= Suresh=0A= =0A= On Aug 8, 2013, at 12:12 PM, Saminda Wijeratne wrote:= =0A= =0A= > +1 for the suggestion by Viknes.=0A= >=0A= > Also +1 on Shameera's suggestion as well.=0A= > Shameera, you obviously have thought of this very hard. Do you think we n= eed to plan & implement the versioning url you mentioned along with the non= -versioned url or can we do the non-versioned url first and then implement = the versioned url with less changes to map the non-versioned url to the lat= est version url?=0A= >=0A= > Saminda=0A= >=0A= >=0A= > On Thu, Aug 8, 2013 at 4:35 AM, Shameera Rathnayaka wrote:=0A= > Hi Saminda etal,=0A= >=0A= > Sometimes back i have done simple background research regarding best way = to add versioning support to REST API. Base on that Here i am like to sugg= est improved version of your second URL set, that we can add versioning sup= port for this REST API, Hope this would help.=0A= >=0A= > Versioning support=0A= >=0A= > Putting the version in the URI makes the API easier to use, test, and ver= ify that the appropriate resource representation version is being requested= . The current recommendation is to support versioning via version numbers d= irectly in resource URIs. It makes the version visible and a versioned API = is easier to understand and use correctly.=0A= >=0A= > Version numbers in URIs should be high in the node hierarchy, preferably = as the first node, for example:=0A= >=0A= >=0A= > http[s]://:// or http[s]:/= /:/api//=0A= >=0A= >=0A= > Lets say we have released two Airavata registry REST API versions(v1 and = v2). For the latest API version(here it's v2) we will have two URIs for eac= h resource as shown in below=0A= >=0A= > http://airavataserver:8090/api/airavata-services/registry/ and=0A= >=0A= > http://airavataserver:8090/api/v2/airavata-services/registry/=0A= >=0A= > For old versions(here v1) we will have only one URI for each resource=0A= >=0A= > eg: http://airavataserver:8090/api/v1/airavata-services/registry/=0A= >=0A= > With this approach if users need to always use the latest REST API with t= heir products then they can use version abasent URI's which always map to t= he latest released version of REST API=0A= >=0A= > eg: http://airavataserver:8090/api/airavata-services/registry/ - always = map to latest released API version=0A= >=0A= > If user need to use specific version of REST API then it can be done by u= sing URIs which have version number attached to it.=0A= >=0A= > eg: http://airavataserver:8090/api/v2/airavata-services/registry/ - alway= s map to version 2.=0A= >=0A= > Thanks,=0A= > Shameera.=0A= >=0A= >=0A= >=0A= >=0A= > On Thu, Aug 8, 2013 at 6:47 AM, Viknes Balasubramanee w= rote:=0A= > How about something like=0A= >=0A= > http://<...deployed_host_path...>/airavata/services/registry/ (Dropping t= he =96api makes sense as whatever is accessible should be an api)=0A= >=0A= > http://<...deployed_host_path...>/airavata/services/experiment/=0A= >=0A= > If we have a sample webapp deployed or if we decide to add anything else = later on, it can go like=0A= >=0A= > http://<...deployed_host_path...>/airavata/{{webappname}}/=0A= >=0A= >=0A= >=0A= > Viknes=0A= >=0A= >=0A= >=0A= > From: Saminda Wijeratne [mailto:samindaw@gmail.com]=0A= > Sent: Wednesday, August 07, 2013 11:07 PM=0A= > To: dev@airavata.apache.org; dev@airavata.apache.org=0A= > Subject: Re: Changing the registry rest service context & url=0A= >=0A= >=0A= >=0A= > Perhaps the following could be a better URL pattern,=0A= >=0A= > http://<...host_path...>/airavata-services/user-store/....=0A= > http://<...host_path...>/airavata-services/registry/....=0A= >=0A= > http://<...host_path...>/airavata-services/experiment/....=0A= >=0A= > eg:=0A= >=0A= > http://<...host_path...>/airavata-services/experiment/execution/workflow?= templateId=3Dxxx....=0A= > http://<...host_path...>/airavata-services/experiment/execution/cancel?ex= perimentId=3Dxxx=0A= > http://<...host_path...>/airavata-services/experiment/execution/suspend?e= xperimentId=3Dxxx=0A= > http://<...host_path...>/airavata-services/experiment/execution/resume?ex= perimentId=3Dxxx=0A= >=0A= >=0A= >=0A= >=0A= > On Wed, Aug 7, 2013 at 12:42 PM, Suresh Marru wrote:= =0A= >=0A= > This makes good sense and probably about time to do it as well.=0A= >=0A= > + 1 for the change.=0A= >=0A= > Suresh=0A= >=0A= > On Aug 7, 2013, at 11:59 AM, Saminda Wijeratne wrote= :=0A= >=0A= > > Hi devs,=0A= > >=0A= > > With the introduction of the rest service for experiment execution I th= ink we need to have a proper service hosting url mechanism. Current registr= y rest service is hosted as,=0A= > > http://<...deployed_host_path...>/airavata-registry/api/.... which I c= hanged to,=0A= > > http://<...deployed_host_path...>/airavata-services/registry-api/....= =0A= > >=0A= > >=0A= > > Following is how we can have the new experiment service url=0A= > > http://<...deployed_host_path...>/airavata-services/experiment-service/= ....=0A= > >=0A= > > This is not finalized. Your thoughts are welcome.=0A= > >=0A= > > Regards,=0A= > > Saminda=0A= >=0A= >=0A= >=0A= >=0A= >=0A= >=0A= > --=0A= > Best Regards,=0A= > Shameera Rathnayaka.=0A= >=0A= > email: shameera AT apache.org , shameerainfo AT gmail.com=0A= > Blog : http://shameerarathnayaka.blogspot.com/=0A= >=0A= =0A=