You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@airavata.apache.org by Saminda Wijeratne <sa...@gmail.com> on 2013/08/07 17:59:39 UTC
Changing the registry rest service context & url
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
Re: Changing the registry rest service context & url
Posted by Shameera Rathnayaka <sh...@gmail.com>.
Hi Saminda,
In my opinion better way to do this is use URL format like
http://airavataserver:8090/api/airavata-services/registry/ (Note the "api"
part in the url) Even this is non-versioned but the latest URL this is
inline with versioned URL format too. Once we come up with versioning
support, we can change this to
http://airavataserver:8090/api/v1/airavata-services/registry/<http://airavataserver:8090/api/airavata-services/registry/>(Note
"api/v1" ). Only need to add "v1" for servlet mapping.
Thanks,
Shameera.
On Thu, Aug 8, 2013 at 9:42 PM, Saminda Wijeratne <sa...@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 <vi...@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://%3c...host_path...%3e/airavata-services/user-store/>
>>> *....*
>>> http://<...host_path...>/*airavata-services/registry/*<http://%3c...host_path...%3e/airavata-services/registry/>
>>> *....*****
>>>
>>> http://<...host_path...>/*airavata-services/experiment/*<http://%3c...host_path...%3e/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 <sm...@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 <sa...@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/
>>
>
>
--
Best Regards,
Shameera Rathnayaka.
email: shameera AT apache.org , shameerainfo AT gmail.com
Blog : http://shameerarathnayaka.blogspot.com/
Re: Changing the registry rest service context & url
Posted by Marlon Pierce <ma...@iu.edu>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
The list looks like a great resource.
Marlon
On 8/8/13 1:56 PM, Suresh Marru wrote:
> Got it!. I might just be a leacher on the archives. I am finding
> some very useful and relevant discussion of the topics we discussed
> on Airavata API's before. Mainly the internal component level API's
> and external user facing API's. Hopefully we can learn from the
> crew who is thinking on the topic deeply.
>
> Suresh
>
>
> On Aug 8, 2013, at 1:41 PM, Rion Dooley <do...@tacc.utexas.edu>
> wrote:
>
>> Keep the audience in mind and the rules of the group. People
>> represent themselves, not their companies. Many of those people
>> work at and are primary influencers behind the major social and
>> business service providers, so their use cases are often based on
>> different use cases and experiences.
>>
>> Rion
>>
>> ________________________________________ From: Suresh Marru
>> [smarru@apache.org] Sent: Thursday, August 08, 2013 12:38 PM To:
>> Rion Dooley Cc: dev@airavata.apache.org Subject: Re: Changing the
>> registry rest service context & url
>>
>> 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 <do...@tacc.utexas.edu>
>> 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 [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
>>> <sa...@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
>>>> <sh...@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
>>>> <vi...@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
>>>> <sm...@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
>>>> <sa...@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/
>>>>
>>>
>>
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG/MacGPG2 v2.0.18 (Darwin)
Comment: GPGTools - http://gpgtools.org
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
iQEcBAEBAgAGBQJSA922AAoJEOEgD2XReDo5gkUH/3RgnhpztPdp68/KLmu+AKgv
hlRZf9k9+CjpcLMU0CrYqdv7hGAMgzCRALwirOb2M/jEvUHYGIZOuYobCXWWmTtq
g4CP2jL409LzH8J1mXikR6GkfDpcrJX79/k5LieZGNdD8oYjgWgTF1d514iRRUE/
GLogcg/uJgy6UdMjl+5ljFNVwQopWQMdCxKMg6vqR8jCC4sp8xV7ViUY9KKaZ7Ao
5NyoV8cHt2k6o0IZFBp1NWqT7kEip9mdh4vUwFVT4GdSV6/WIXoUMu1GRkdeK67p
FPP2/KdVTymnx8qLRAGis52sZ6ueQDfJ/oEywhhL68gVfy5SoouNnlATVFLgiMw=
=w3YE
-----END PGP SIGNATURE-----
Re: Changing the registry rest service context & url
Posted by Suresh Marru <sm...@apache.org>.
Got it!. I might just be a leacher on the archives. I am finding some very useful and relevant discussion of the topics we discussed on Airavata API's before. Mainly the internal component level API's and external user facing API's. Hopefully we can learn from the crew who is thinking on the topic deeply.
Suresh
On Aug 8, 2013, at 1:41 PM, Rion Dooley <do...@tacc.utexas.edu> wrote:
> Keep the audience in mind and the rules of the group. People represent themselves, not their companies. Many of those people work at and are primary influencers behind the major social and business service providers, so their use cases are often based on different use cases and experiences.
>
> Rion
>
> ________________________________________
> From: Suresh Marru [smarru@apache.org]
> Sent: Thursday, August 08, 2013 12:38 PM
> To: Rion Dooley
> Cc: dev@airavata.apache.org
> Subject: Re: Changing the registry rest service context & url
>
> 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 <do...@tacc.utexas.edu> 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 [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 <sa...@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 <sh...@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 <vi...@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 <sm...@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 <sa...@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/
>>>
>>
>
RE: Changing the registry rest service context & url
Posted by Rion Dooley <do...@tacc.utexas.edu>.
Keep the audience in mind and the rules of the group. People represent themselves, not their companies. Many of those people work at and are primary influencers behind the major social and business service providers, so their use cases are often based on different use cases and experiences.
Rion
________________________________________
From: Suresh Marru [smarru@apache.org]
Sent: Thursday, August 08, 2013 12:38 PM
To: Rion Dooley
Cc: dev@airavata.apache.org
Subject: Re: Changing the registry rest service context & url
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 <do...@tacc.utexas.edu> 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 [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 <sa...@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 <sh...@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 <vi...@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 <sm...@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 <sa...@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/
>>
>
Re: Changing the registry rest service context & url
Posted by Suresh Marru <sm...@apache.org>.
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 <do...@tacc.utexas.edu> 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 [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 <sa...@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 <sh...@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 <vi...@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 <sm...@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 <sa...@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/
>>
>
RE: Changing the registry rest service context & url
Posted by Rion Dooley <do...@tacc.utexas.edu>.
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 <sa...@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 <sh...@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 <vi...@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 <sm...@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 <sa...@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/
>
Re: Changing the registry rest service context & url
Posted by Suresh Marru <sm...@apache.org>.
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 <sa...@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 <sh...@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 <vi...@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 <sm...@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 <sa...@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/
>
Re: Changing the registry rest service context & url
Posted by Saminda Wijeratne <sa...@gmail.com>.
+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
<sh...@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 <vi...@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://%3c...host_path...%3e/airavata-services/user-store/>
>> *....*
>> http://<...host_path...>/*airavata-services/registry/*<http://%3c...host_path...%3e/airavata-services/registry/>
>> *....*****
>>
>> http://<...host_path...>/*airavata-services/experiment/*<http://%3c...host_path...%3e/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 <sm...@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 <sa...@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/
>
Re: Changing the registry rest service context & url
Posted by Shameera Rathnayaka <sh...@gmail.com>.
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 <vi...@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://%3c...host_path...%3e/airavata-services/user-store/>
> *....*
> http://<...host_path...>/*airavata-services/registry/*<http://%3c...host_path...%3e/airavata-services/registry/>
> *....*****
>
> http://<...host_path...>/*airavata-services/experiment/*<http://%3c...host_path...%3e/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 <sm...@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 <sa...@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/
RE: Changing the registry rest service context & url
Posted by Viknes Balasubramanee <vi...@msn.com>.
How about something like
http:// <http://%3c...deployed_host_path...%3e/airavata/services/registry/>
<...deployed_host_path...>/airavata/services/registry/ (Dropping the -api
makes sense as whatever is accessible should be an api)
http://
<http://%3c...deployed_host_path...%3e/airavata/services/experiment/>
<...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://
<http://%3c...deployed_host_path...%3e/airavata/%7b%7bwebappname%7d%7d/>
<...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:// <http://%3c...host_path...%3e/airavata-services/user-store/>
<...host_path...>/airavata-services/user-store/....
http:// <http://%3c...host_path...%3e/airavata-services/registry/>
<...host_path...>/airavata-services/registry/....
http:// <http://%3c...host_path...%3e/airavata-services/experiment/>
<...host_path...>/airavata-services/experiment/....
eg:
http://
<http://%3c...host_path...%3e/airavata-services/experiment/execution/workflo
w?templateId=xxx>
<...host_path...>/airavata-services/experiment/execution/workflow?templateId
=xxx....
http://
<http://%3c...host_path...%3e/airavata-services/experiment/execution/cancel?
experimentId=xxx>
<...host_path...>/airavata-services/experiment/execution/cancel?experimentId
=xxx
http://
<http://%3c...host_path...%3e/airavata-services/experiment/execution/suspend
?experimentId=xxx>
<...host_path...>/airavata-services/experiment/execution/suspend?experimentI
d=xxx
http://
<http://%3c...host_path...%3e/airavata-services/experiment/execution/resume?
experimentId=xxx>
<...host_path...>/airavata-services/experiment/execution/resume?experimentId
=xxx
On Wed, Aug 7, 2013 at 12:42 PM, Suresh Marru <smarru@apache.org
<ma...@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
<ma...@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:// <http://%3c...deployed_host_path...%3e/airavata-registry/api/>
<...deployed_host_path...>/airavata-registry/api/.... which I changed to,
> http://
<http://%3c...deployed_host_path...%3e/airavata-services/registry-api/>
<...deployed_host_path...>/airavata-services/registry-api/....
>
>
> Following is how we can have the new experiment service url
> http://
<http://%3c...deployed_host_path...%3e/airavata-services/experiment-service/
> <...deployed_host_path...>/airavata-services/experiment-service/....
>
> This is not finalized. Your thoughts are welcome.
>
> Regards,
> Saminda
Re: Changing the registry rest service context & url
Posted by Chathuri Wimalasena <ka...@gmail.com>.
+1 for the second set of URL patterns.
Regards,
Chathuri
On Wed, Aug 7, 2013 at 1:36 PM, Saminda Wijeratne <sa...@gmail.com>wrote:
> 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-servi**ces/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 <sm...@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 <sa...@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
>>
>>
>
Re: Changing the registry rest service context & url
Posted by Saminda Wijeratne <sa...@gmail.com>.
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-servi**ces/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 <sm...@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 <sa...@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
>
>
Re: Changing the registry rest service context & url
Posted by Suresh Marru <sm...@apache.org>.
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 <sa...@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