airavata-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rion Dooley <doo...@tacc.utexas.edu>
Subject RE: Changing the registry rest service context & url
Date Thu, 08 Aug 2013 17:33:02 GMT
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 [smarru@apache.org]
Sent: Thursday, August 08, 2013 11:23 AM
To: dev@airavata.apache.org
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 <samindaw@gmail.com> 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 <shameerainfo@gmail.com> 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 <viknesb@msn.com> 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:samindaw@gmail.com]
> Sent: Wednesday, August 07, 2013 11:07 PM
> To: dev@airavata.apache.org; dev@airavata.apache.org
> 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 <smarru@apache.org> 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 <samindaw@gmail.com> 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/
>


Mime
View raw message