Thanks Rion, it is indeed very helpfull to hear your experience. Also appreciate the api-craft pointer, I am already overwhelmed with the api versioning thread - https://groups.google.com/forum/#!topic/api-craft/E8MBkzirdcw
Suresh On Aug 8, 2013, at 1:33 PM, Rion Dooley <[email protected]> wrote: > Short answer is I would add v2 to the url. > > The long answer is that my thinking on this changed recently. I used to think > that a constant URL structure with the version included in the content type > 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 actually > harder on your clients to deal with a constant url that one with the version > in the URL. The reason being that when you upgrade the primary API, their > 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 > errors. 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 headers > and the Content-Type, you're adding complexity when what you want to do is > remove it. > > 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 apis > and dealing with versioning issues over time. YOu might want to join the > api-craft google group to read some other opinions. > https://groups.google.com/forum/#!forum/api-craft > > > Rion > ________________________________________ > From: Suresh Marru [[email protected]] > Sent: Thursday, August 08, 2013 11:23 AM > To: [email protected] > Cc: Rion Dooley > Subject: Re: Changing the registry rest service context & url > > Hi Rion, > > We will appreciate your advises on API Naming conventions based on your > experiences with Foundation API - https://foundation.iplantcollaborative.org/ > > Thanks, > Suresh > > On Aug 8, 2013, at 12:12 PM, Saminda Wijeratne <[email protected]> wrote: > >> +1 for the suggestion by Viknes. >> >> Also +1 on Shameera's suggestion as well. >> Shameera, you obviously have thought of this very hard. Do you think we need >> 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 latest version url? >> >> Saminda >> >> >> On Thu, Aug 8, 2013 at 4:35 AM, Shameera Rathnayaka <[email protected]> >> wrote: >> Hi Saminda etal, >> >> 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 suggest >> improved version of your second URL set, that we can add versioning support >> for this REST API, Hope this would help. >> >> Versioning support >> >> Putting the version in the URI makes the API easier to use, test, and verify >> that the appropriate resource representation version is being requested. The >> current recommendation is to support versioning via version numbers directly >> in resource URIs. It makes the version visible and a versioned API is easier >> to understand and use correctly. >> >> Version numbers in URIs should be high in the node hierarchy, preferably as >> the first node, for example: >> >> >> http[s]://<hostname>:<port>/<version.of.api>/<resource-path> or >> http[s]://<hostname>:<port>/api/<version.of.api>/<resource-path> >> >> >> 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 each >> resource as shown in below >> >> http://airavataserver:8090/api/airavata-services/registry/ and >> >> http://airavataserver:8090/api/v2/airavata-services/registry/ >> >> For old versions(here v1) we will have only one URI for each resource >> >> eg: http://airavataserver:8090/api/v1/airavata-services/registry/ >> >> With this approach if users need to always use the latest REST API with >> their products then they can use version abasent URI's which always map to >> the latest released version of REST API >> >> eg: http://airavataserver:8090/api/airavata-services/registry/ - always map >> to latest released API version >> >> If user need to use specific version of REST API then it can be done by >> using URIs which have version number attached to it. >> >> eg: http://airavataserver:8090/api/v2/airavata-services/registry/ - always >> map to version 2. >> >> Thanks, >> Shameera. >> >> >> >> >> On Thu, Aug 8, 2013 at 6:47 AM, Viknes Balasubramanee <[email protected]> >> wrote: >> How about something like >> >> http://<...deployed_host_path...>/airavata/services/registry/ (Dropping the >> –api makes sense as whatever is accessible should be an api) >> >> http://<...deployed_host_path...>/airavata/services/experiment/ >> >> If we have a sample webapp deployed or if we decide to add anything else >> later on, it can go like >> >> http://<...deployed_host_path...>/airavata/{{webappname}}/ >> >> >> >> Viknes >> >> >> >> From: Saminda Wijeratne [mailto:[email protected]] >> Sent: Wednesday, August 07, 2013 11:07 PM >> To: [email protected]; [email protected] >> Subject: Re: Changing the registry rest service context & url >> >> >> >> Perhaps the following could be a better URL pattern, >> >> http://<...host_path...>/airavata-services/user-store/.... >> http://<...host_path...>/airavata-services/registry/.... >> >> http://<...host_path...>/airavata-services/experiment/.... >> >> eg: >> >> http://<...host_path...>/airavata-services/experiment/execution/workflow?templateId=xxx.... >> http://<...host_path...>/airavata-services/experiment/execution/cancel?experimentId=xxx >> http://<...host_path...>/airavata-services/experiment/execution/suspend?experimentId=xxx >> http://<...host_path...>/airavata-services/experiment/execution/resume?experimentId=xxx >> >> >> >> >> On Wed, Aug 7, 2013 at 12:42 PM, Suresh Marru <[email protected]> wrote: >> >> This makes good sense and probably about time to do it as well. >> >> + 1 for the change. >> >> Suresh >> >> On Aug 7, 2013, at 11:59 AM, Saminda Wijeratne <[email protected]> wrote: >> >>> Hi devs, >>> >>> With the introduction of the rest service for experiment execution I think >>> we need to have a proper service hosting url mechanism. Current registry >>> rest service is hosted as, >>> http://<...deployed_host_path...>/airavata-registry/api/.... which I >>> changed to, >>> http://<...deployed_host_path...>/airavata-services/registry-api/.... >>> >>> >>> Following is how we can have the new experiment service url >>> http://<...deployed_host_path...>/airavata-services/experiment-service/.... >>> >>> This is not finalized. Your thoughts are welcome. >>> >>> Regards, >>> Saminda >> >> >> >> >> >> >> -- >> Best Regards, >> Shameera Rathnayaka. >> >> email: shameera AT apache.org , shameerainfo AT gmail.com >> Blog : http://shameerarathnayaka.blogspot.com/ >> >
