You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@stratos.apache.org by Nirmal Fernando <ni...@gmail.com> on 2014/10/05 17:57:14 UTC

Versioning Stratos REST API

All,

Let's discuss how we could do $subject properly. AFAIS currently we don't
have any versioning in our REST API, but we have consumers of our REST API.

1. We can make the default API version to be the latest version, i.e. v2.

So, if someone send a request to /<rootContext>/cartridges , it would find
/<rootContext>/v2/cartridges

2. Anyone can use the default API paths and still could request for a
specific version via HTTP Accept Header.

Accept: application/vnd.stratos.v1+json


3. Provide a migration guide for existing Clients.

- If they want to use the old API, they need to specifically request for
the old API, by specifying the Accept header.

4. Mark v1 API as deprecated and announce that we'll remove the support for
it in the next release.

Any other alternatives?


-- 
Best Regards,
Nirmal

Nirmal Fernando.
PPMC Member & Committer of Apache Stratos,
Senior Software Engineer, WSO2 Inc.

Blog: http://nirmalfdo.blogspot.com/

Re: Versioning Stratos REST API

Posted by Gayan Gunarathne <ga...@wso2.com>.
AFAIK if the REST API using the headers for version purposes, customer need
only to change the header part only when the version update.IMO If we want
we can use the custom header instead of the accept header as for the W3
protocol standards accept header used for specify the media type.(As Imesh
mention).But I think GIT uses Accept header as some proxy servers may
filter custom-headers.

+1 for use the both accept header and the URL context. I guess then it will
be easy for support in case of the REST API version update.

Thanks,
Gayan


On Mon, Oct 6, 2014 at 4:13 PM, Shiroshica Kulatilake <sh...@wso2.com>
wrote:

>
> So if I am a client who is currently using the REST API of Stratos I will
> have to change my client to send the version in the header as mentioned in
> this thread in order to use the previous endpoints  - Assuming that these
> endpoints will be maintained till next release.
>
> However, As per the discussion on the thread *"Stratos REST API root
> context"* if we change the root context then can we do the above ?
>
>
>
> On Mon, Oct 6, 2014 at 3:04 PM, Nirmal Fernando <ni...@gmail.com>
> wrote:
>
>> Sorry, if I wasn't clear Imesh. Yes, we will support both. Accept header
>> can be used in a scenario where you want to explicitly mention the API
>> version when accessing via default API path. If you wish to use the URL
>> context, you shouldn't be required to set the Accept header.
>>
>> On Mon, Oct 6, 2014 at 2:56 PM, Imesh Gunaratne <im...@apache.org> wrote:
>>
>>> Got it! Shall we support both Accept header and URL context for this?
>>>
>>> Thanks
>>>
>>> On Mon, Oct 6, 2014 at 2:39 PM, Nirmal Fernando <ni...@gmail.com>
>>> wrote:
>>>
>>>> Hi Imesh,
>>>>
>>>> Yes, GitHub API does that way https://developer.github.com/v3/versions/
>>>>
>>>>
>>>> On Mon, Oct 6, 2014 at 2:35 PM, Imesh Gunaratne <im...@apache.org>
>>>> wrote:
>>>>
>>>>> +1 Regarding point 2: using Accept header to specify the API version,
>>>>> is this being done by any other known APIs? For my understanding Accept
>>>>> header is used for specify the media type [1].
>>>>>
>>>>> [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
>>>>>
>>>>> On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <
>>>>> nirmal070125@gmail.com> wrote:
>>>>>
>>>>>> All,
>>>>>>
>>>>>> Let's discuss how we could do $subject properly. AFAIS currently we
>>>>>> don't have any versioning in our REST API, but we have consumers of our
>>>>>> REST API.
>>>>>>
>>>>>> 1. We can make the default API version to be the latest version, i.e.
>>>>>> v2.
>>>>>>
>>>>>> So, if someone send a request to /<rootContext>/cartridges , it would
>>>>>> find /<rootContext>/v2/cartridges
>>>>>>
>>>>>> 2. Anyone can use the default API paths and still could request for a
>>>>>> specific version via HTTP Accept Header.
>>>>>>
>>>>>> Accept: application/vnd.stratos.v1+json
>>>>>>
>>>>>>
>>>>>> 3. Provide a migration guide for existing Clients.
>>>>>>
>>>>>> - If they want to use the old API, they need to specifically request
>>>>>> for the old API, by specifying the Accept header.
>>>>>>
>>>>>> 4. Mark v1 API as deprecated and announce that we'll remove the
>>>>>> support for it in the next release.
>>>>>>
>>>>>> Any other alternatives?
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Best Regards,
>>>>>> Nirmal
>>>>>>
>>>>>> Nirmal Fernando.
>>>>>> PPMC Member & Committer of Apache Stratos,
>>>>>> Senior Software Engineer, WSO2 Inc.
>>>>>>
>>>>>> Blog: http://nirmalfdo.blogspot.com/
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Imesh Gunaratne
>>>>>
>>>>> Technical Lead, WSO2
>>>>> Committer & PMC Member, Apache Stratos
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Best Regards,
>>>> Nirmal
>>>>
>>>> Nirmal Fernando.
>>>> PPMC Member & Committer of Apache Stratos,
>>>> Senior Software Engineer, WSO2 Inc.
>>>>
>>>> Blog: http://nirmalfdo.blogspot.com/
>>>>
>>>
>>>
>>>
>>> --
>>> Imesh Gunaratne
>>>
>>> Technical Lead, WSO2
>>> Committer & PMC Member, Apache Stratos
>>>
>>
>>
>>
>> --
>> Best Regards,
>> Nirmal
>>
>> Nirmal Fernando.
>> PPMC Member & Committer of Apache Stratos,
>> Senior Software Engineer, WSO2 Inc.
>>
>> Blog: http://nirmalfdo.blogspot.com/
>>
>
>
>
> --
> Shiroshica Kulatilake
>
> Architect,
> WSO2, Inc. http://wso2.com/
> Phone: +94 776523867
>



-- 
Best Regards,

Gayan Gunarathne
Technical Lead
WSO2 Inc. (http://wso2.com)
email  : gayang@wso2.com  | mobile : +94 766819985

Re: Versioning Stratos REST API

Posted by Shiroshica Kulatilake <sh...@wso2.com>.
So if I am a client who is currently using the REST API of Stratos I will
have to change my client to send the version in the header as mentioned in
this thread in order to use the previous endpoints  - Assuming that these
endpoints will be maintained till next release.

However, As per the discussion on the thread *"Stratos REST API root
context"* if we change the root context then can we do the above ?



On Mon, Oct 6, 2014 at 3:04 PM, Nirmal Fernando <ni...@gmail.com>
wrote:

> Sorry, if I wasn't clear Imesh. Yes, we will support both. Accept header
> can be used in a scenario where you want to explicitly mention the API
> version when accessing via default API path. If you wish to use the URL
> context, you shouldn't be required to set the Accept header.
>
> On Mon, Oct 6, 2014 at 2:56 PM, Imesh Gunaratne <im...@apache.org> wrote:
>
>> Got it! Shall we support both Accept header and URL context for this?
>>
>> Thanks
>>
>> On Mon, Oct 6, 2014 at 2:39 PM, Nirmal Fernando <ni...@gmail.com>
>> wrote:
>>
>>> Hi Imesh,
>>>
>>> Yes, GitHub API does that way https://developer.github.com/v3/versions/
>>>
>>>
>>> On Mon, Oct 6, 2014 at 2:35 PM, Imesh Gunaratne <im...@apache.org>
>>> wrote:
>>>
>>>> +1 Regarding point 2: using Accept header to specify the API version,
>>>> is this being done by any other known APIs? For my understanding Accept
>>>> header is used for specify the media type [1].
>>>>
>>>> [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
>>>>
>>>> On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <nirmal070125@gmail.com
>>>> > wrote:
>>>>
>>>>> All,
>>>>>
>>>>> Let's discuss how we could do $subject properly. AFAIS currently we
>>>>> don't have any versioning in our REST API, but we have consumers of our
>>>>> REST API.
>>>>>
>>>>> 1. We can make the default API version to be the latest version, i.e.
>>>>> v2.
>>>>>
>>>>> So, if someone send a request to /<rootContext>/cartridges , it would
>>>>> find /<rootContext>/v2/cartridges
>>>>>
>>>>> 2. Anyone can use the default API paths and still could request for a
>>>>> specific version via HTTP Accept Header.
>>>>>
>>>>> Accept: application/vnd.stratos.v1+json
>>>>>
>>>>>
>>>>> 3. Provide a migration guide for existing Clients.
>>>>>
>>>>> - If they want to use the old API, they need to specifically request
>>>>> for the old API, by specifying the Accept header.
>>>>>
>>>>> 4. Mark v1 API as deprecated and announce that we'll remove the
>>>>> support for it in the next release.
>>>>>
>>>>> Any other alternatives?
>>>>>
>>>>>
>>>>> --
>>>>> Best Regards,
>>>>> Nirmal
>>>>>
>>>>> Nirmal Fernando.
>>>>> PPMC Member & Committer of Apache Stratos,
>>>>> Senior Software Engineer, WSO2 Inc.
>>>>>
>>>>> Blog: http://nirmalfdo.blogspot.com/
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Imesh Gunaratne
>>>>
>>>> Technical Lead, WSO2
>>>> Committer & PMC Member, Apache Stratos
>>>>
>>>
>>>
>>>
>>> --
>>> Best Regards,
>>> Nirmal
>>>
>>> Nirmal Fernando.
>>> PPMC Member & Committer of Apache Stratos,
>>> Senior Software Engineer, WSO2 Inc.
>>>
>>> Blog: http://nirmalfdo.blogspot.com/
>>>
>>
>>
>>
>> --
>> Imesh Gunaratne
>>
>> Technical Lead, WSO2
>> Committer & PMC Member, Apache Stratos
>>
>
>
>
> --
> Best Regards,
> Nirmal
>
> Nirmal Fernando.
> PPMC Member & Committer of Apache Stratos,
> Senior Software Engineer, WSO2 Inc.
>
> Blog: http://nirmalfdo.blogspot.com/
>



-- 
Shiroshica Kulatilake

Architect,
WSO2, Inc. http://wso2.com/
Phone: +94 776523867

Re: Versioning Stratos REST API

Posted by Nirmal Fernando <ni...@gmail.com>.
Sorry, if I wasn't clear Imesh. Yes, we will support both. Accept header
can be used in a scenario where you want to explicitly mention the API
version when accessing via default API path. If you wish to use the URL
context, you shouldn't be required to set the Accept header.

On Mon, Oct 6, 2014 at 2:56 PM, Imesh Gunaratne <im...@apache.org> wrote:

> Got it! Shall we support both Accept header and URL context for this?
>
> Thanks
>
> On Mon, Oct 6, 2014 at 2:39 PM, Nirmal Fernando <ni...@gmail.com>
> wrote:
>
>> Hi Imesh,
>>
>> Yes, GitHub API does that way https://developer.github.com/v3/versions/
>>
>>
>> On Mon, Oct 6, 2014 at 2:35 PM, Imesh Gunaratne <im...@apache.org> wrote:
>>
>>> +1 Regarding point 2: using Accept header to specify the API version, is
>>> this being done by any other known APIs? For my understanding Accept header
>>> is used for specify the media type [1].
>>>
>>> [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
>>>
>>> On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <ni...@gmail.com>
>>> wrote:
>>>
>>>> All,
>>>>
>>>> Let's discuss how we could do $subject properly. AFAIS currently we
>>>> don't have any versioning in our REST API, but we have consumers of our
>>>> REST API.
>>>>
>>>> 1. We can make the default API version to be the latest version, i.e.
>>>> v2.
>>>>
>>>> So, if someone send a request to /<rootContext>/cartridges , it would
>>>> find /<rootContext>/v2/cartridges
>>>>
>>>> 2. Anyone can use the default API paths and still could request for a
>>>> specific version via HTTP Accept Header.
>>>>
>>>> Accept: application/vnd.stratos.v1+json
>>>>
>>>>
>>>> 3. Provide a migration guide for existing Clients.
>>>>
>>>> - If they want to use the old API, they need to specifically request
>>>> for the old API, by specifying the Accept header.
>>>>
>>>> 4. Mark v1 API as deprecated and announce that we'll remove the support
>>>> for it in the next release.
>>>>
>>>> Any other alternatives?
>>>>
>>>>
>>>> --
>>>> Best Regards,
>>>> Nirmal
>>>>
>>>> Nirmal Fernando.
>>>> PPMC Member & Committer of Apache Stratos,
>>>> Senior Software Engineer, WSO2 Inc.
>>>>
>>>> Blog: http://nirmalfdo.blogspot.com/
>>>>
>>>
>>>
>>>
>>> --
>>> Imesh Gunaratne
>>>
>>> Technical Lead, WSO2
>>> Committer & PMC Member, Apache Stratos
>>>
>>
>>
>>
>> --
>> Best Regards,
>> Nirmal
>>
>> Nirmal Fernando.
>> PPMC Member & Committer of Apache Stratos,
>> Senior Software Engineer, WSO2 Inc.
>>
>> Blog: http://nirmalfdo.blogspot.com/
>>
>
>
>
> --
> Imesh Gunaratne
>
> Technical Lead, WSO2
> Committer & PMC Member, Apache Stratos
>



-- 
Best Regards,
Nirmal

Nirmal Fernando.
PPMC Member & Committer of Apache Stratos,
Senior Software Engineer, WSO2 Inc.

Blog: http://nirmalfdo.blogspot.com/

Re: Versioning Stratos REST API

Posted by Imesh Gunaratne <im...@apache.org>.
Got it! Shall we support both Accept header and URL context for this?

Thanks

On Mon, Oct 6, 2014 at 2:39 PM, Nirmal Fernando <ni...@gmail.com>
wrote:

> Hi Imesh,
>
> Yes, GitHub API does that way https://developer.github.com/v3/versions/
>
>
> On Mon, Oct 6, 2014 at 2:35 PM, Imesh Gunaratne <im...@apache.org> wrote:
>
>> +1 Regarding point 2: using Accept header to specify the API version, is
>> this being done by any other known APIs? For my understanding Accept header
>> is used for specify the media type [1].
>>
>> [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
>>
>> On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <ni...@gmail.com>
>> wrote:
>>
>>> All,
>>>
>>> Let's discuss how we could do $subject properly. AFAIS currently we
>>> don't have any versioning in our REST API, but we have consumers of our
>>> REST API.
>>>
>>> 1. We can make the default API version to be the latest version, i.e. v2.
>>>
>>> So, if someone send a request to /<rootContext>/cartridges , it would
>>> find /<rootContext>/v2/cartridges
>>>
>>> 2. Anyone can use the default API paths and still could request for a
>>> specific version via HTTP Accept Header.
>>>
>>> Accept: application/vnd.stratos.v1+json
>>>
>>>
>>> 3. Provide a migration guide for existing Clients.
>>>
>>> - If they want to use the old API, they need to specifically request for
>>> the old API, by specifying the Accept header.
>>>
>>> 4. Mark v1 API as deprecated and announce that we'll remove the support
>>> for it in the next release.
>>>
>>> Any other alternatives?
>>>
>>>
>>> --
>>> Best Regards,
>>> Nirmal
>>>
>>> Nirmal Fernando.
>>> PPMC Member & Committer of Apache Stratos,
>>> Senior Software Engineer, WSO2 Inc.
>>>
>>> Blog: http://nirmalfdo.blogspot.com/
>>>
>>
>>
>>
>> --
>> Imesh Gunaratne
>>
>> Technical Lead, WSO2
>> Committer & PMC Member, Apache Stratos
>>
>
>
>
> --
> Best Regards,
> Nirmal
>
> Nirmal Fernando.
> PPMC Member & Committer of Apache Stratos,
> Senior Software Engineer, WSO2 Inc.
>
> Blog: http://nirmalfdo.blogspot.com/
>



-- 
Imesh Gunaratne

Technical Lead, WSO2
Committer & PMC Member, Apache Stratos

Re: Versioning Stratos REST API

Posted by Nirmal Fernando <ni...@gmail.com>.
Hi Imesh,

Yes, GitHub API does that way https://developer.github.com/v3/versions/


On Mon, Oct 6, 2014 at 2:35 PM, Imesh Gunaratne <im...@apache.org> wrote:

> +1 Regarding point 2: using Accept header to specify the API version, is
> this being done by any other known APIs? For my understanding Accept header
> is used for specify the media type [1].
>
> [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
>
> On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <ni...@gmail.com>
> wrote:
>
>> All,
>>
>> Let's discuss how we could do $subject properly. AFAIS currently we don't
>> have any versioning in our REST API, but we have consumers of our REST API.
>>
>> 1. We can make the default API version to be the latest version, i.e. v2.
>>
>> So, if someone send a request to /<rootContext>/cartridges , it would
>> find /<rootContext>/v2/cartridges
>>
>> 2. Anyone can use the default API paths and still could request for a
>> specific version via HTTP Accept Header.
>>
>> Accept: application/vnd.stratos.v1+json
>>
>>
>> 3. Provide a migration guide for existing Clients.
>>
>> - If they want to use the old API, they need to specifically request for
>> the old API, by specifying the Accept header.
>>
>> 4. Mark v1 API as deprecated and announce that we'll remove the support
>> for it in the next release.
>>
>> Any other alternatives?
>>
>>
>> --
>> Best Regards,
>> Nirmal
>>
>> Nirmal Fernando.
>> PPMC Member & Committer of Apache Stratos,
>> Senior Software Engineer, WSO2 Inc.
>>
>> Blog: http://nirmalfdo.blogspot.com/
>>
>
>
>
> --
> Imesh Gunaratne
>
> Technical Lead, WSO2
> Committer & PMC Member, Apache Stratos
>



-- 
Best Regards,
Nirmal

Nirmal Fernando.
PPMC Member & Committer of Apache Stratos,
Senior Software Engineer, WSO2 Inc.

Blog: http://nirmalfdo.blogspot.com/

Re: Versioning Stratos REST API

Posted by Imesh Gunaratne <im...@apache.org>.
+1 Regarding point 2: using Accept header to specify the API version, is
this being done by any other known APIs? For my understanding Accept header
is used for specify the media type [1].

[1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <ni...@gmail.com>
wrote:

> All,
>
> Let's discuss how we could do $subject properly. AFAIS currently we don't
> have any versioning in our REST API, but we have consumers of our REST API.
>
> 1. We can make the default API version to be the latest version, i.e. v2.
>
> So, if someone send a request to /<rootContext>/cartridges , it would find
> /<rootContext>/v2/cartridges
>
> 2. Anyone can use the default API paths and still could request for a
> specific version via HTTP Accept Header.
>
> Accept: application/vnd.stratos.v1+json
>
>
> 3. Provide a migration guide for existing Clients.
>
> - If they want to use the old API, they need to specifically request for
> the old API, by specifying the Accept header.
>
> 4. Mark v1 API as deprecated and announce that we'll remove the support
> for it in the next release.
>
> Any other alternatives?
>
>
> --
> Best Regards,
> Nirmal
>
> Nirmal Fernando.
> PPMC Member & Committer of Apache Stratos,
> Senior Software Engineer, WSO2 Inc.
>
> Blog: http://nirmalfdo.blogspot.com/
>



-- 
Imesh Gunaratne

Technical Lead, WSO2
Committer & PMC Member, Apache Stratos

Re: Versioning Stratos REST API

Posted by Chamila De Alwis <ch...@wso2.com>.
Although snake_case improves readability, camelCase is actively enforced
with style guidelines for Java. So it would be best to keep using camelCase
to maintain a consistent code base.


Regards,
Chamila de Alwis
Software Engineer | WSO2 | +94772207163
Blog: code.chamiladealwis.com



On Mon, Oct 6, 2014 at 10:46 AM, Dinesh Bandara <di...@wso2.com> wrote:

> I think it is better to use camelCase since we are using java as our
> underline language
>
> On Mon, Oct 6, 2014 at 10:05 AM, Gayan Gunarathne <ga...@wso2.com> wrote:
>
>> I think camelcase is better as we are using java for developed the REST
>> API.I guess lot of APIs use this as they following naming conventions of
>> the underlying language they are using.Also there are some arguments that
>> snake-case will improve the readability , it may help when documentation
>> and samples.But again it will be conflict with our underline naming
>> convention. WDYT?
>>
>> Thanks,
>> Gayan
>>
>>
>> On Mon, Oct 6, 2014 at 7:32 AM, Nirmal Fernando <ni...@gmail.com>
>> wrote:
>>
>>> Thanks guys for the pointers. I'll create Jiras for all of these.
>>>
>>> On Mon, Oct 6, 2014 at 12:00 AM, Isuru Perera <is...@wso2.com> wrote:
>>>
>>>> I also agree with all points.
>>>>
>>>> On Sun, Oct 5, 2014 at 11:09 PM, Akila Ravihansa Perera <
>>>> ravihansa@wso2.com> wrote:
>>>>
>>>>> Hi,
>>>>>
>>>>> +1 for all the suggested points.
>>>>>
>>>>> I would like to add few more to the list to be considered.
>>>>>
>>>>> 1. Provide useful error messages for back-end API exceptions.
>>>>>
>>>>> 2. Use of snake_case instead of camelCase in APIs. It is much more
>>>>> readable.
>>>>>
>>>>
>>> Do you have any concrete cases where people have used snake-case? I
>>> found Google Kubernetes API is also using camel case:
>>> http://cdn.rawgit.com/GoogleCloudPlatform/kubernetes/31a0daae3627c91bc96e1f02a6344cd76e294791/api/kubernetes.html
>>>
>>>>
>>>>> 3. Support gzip compression.
>>>>>
>>>>> 4. Enable Cross-site Resource Sharing. We cannot make an API call to
>>>>> Stratos REST API through Javascript without this.
>>>>>
>>>> +1. I also faced this issue and Stratos APIs were failing when invoking
>>>> via an application using node.js/jQuery.
>>>>
>>>>>
>>>>>
>>>>>
>>>>> On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <
>>>>> nirmal070125@gmail.com> wrote:
>>>>> > All,
>>>>> >
>>>>> > Let's discuss how we could do $subject properly. AFAIS currently we
>>>>> don't
>>>>> > have any versioning in our REST API, but we have consumers of our
>>>>> REST API.
>>>>> >
>>>>> > 1. We can make the default API version to be the latest version,
>>>>> i.e. v2.
>>>>> >
>>>>> > So, if someone send a request to /<rootContext>/cartridges , it
>>>>> would find
>>>>> > /<rootContext>/v2/cartridges
>>>>> >
>>>>> > 2. Anyone can use the default API paths and still could request for a
>>>>> > specific version via HTTP Accept Header.
>>>>> >
>>>>> > Accept: application/vnd.stratos.v1+json
>>>>> >
>>>>> >
>>>>> > 3. Provide a migration guide for existing Clients.
>>>>> >
>>>>> > - If they want to use the old API, they need to specifically request
>>>>> for the
>>>>> > old API, by specifying the Accept header.
>>>>> >
>>>>> > 4. Mark v1 API as deprecated and announce that we'll remove the
>>>>> support for
>>>>> > it in the next release.
>>>>> >
>>>>> > Any other alternatives?
>>>>> >
>>>>> >
>>>>> > --
>>>>> > Best Regards,
>>>>> > Nirmal
>>>>> >
>>>>> > Nirmal Fernando.
>>>>> > PPMC Member & Committer of Apache Stratos,
>>>>> > Senior Software Engineer, WSO2 Inc.
>>>>> >
>>>>> > Blog: http://nirmalfdo.blogspot.com/
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Akila Ravihansa Perera
>>>>> Software Engineer, WSO2
>>>>>
>>>>> Blog: http://ravihansa3000.blogspot.com
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Isuru Perera
>>>> Senior Software Engineer | WSO2, Inc. | http://wso2.com/
>>>> Lean . Enterprise . Middleware
>>>>
>>>> about.me/chrishantha
>>>>
>>>
>>>
>>>
>>> --
>>> Best Regards,
>>> Nirmal
>>>
>>> Nirmal Fernando.
>>> PPMC Member & Committer of Apache Stratos,
>>> Senior Software Engineer, WSO2 Inc.
>>>
>>> Blog: http://nirmalfdo.blogspot.com/
>>>
>>
>>
>>
>> --
>> Best Regards,
>>
>> Gayan Gunarathne
>> Technical Lead
>> WSO2 Inc. (http://wso2.com)
>> email  : gayang@wso2.com  | mobile : +94 766819985
>>
>>
>
>
>
> --
> *Dinesh Bandara*
> Software Engineer
> WSO2 Inc.; http://wso2.com
> lean.enterprise.middleware
>
>

Re: Versioning Stratos REST API

Posted by Dinesh Bandara <di...@wso2.com>.
I think it is better to use camelCase since we are using java as our
underline language

On Mon, Oct 6, 2014 at 10:05 AM, Gayan Gunarathne <ga...@wso2.com> wrote:

> I think camelcase is better as we are using java for developed the REST
> API.I guess lot of APIs use this as they following naming conventions of
> the underlying language they are using.Also there are some arguments that
> snake-case will improve the readability , it may help when documentation
> and samples.But again it will be conflict with our underline naming
> convention. WDYT?
>
> Thanks,
> Gayan
>
>
> On Mon, Oct 6, 2014 at 7:32 AM, Nirmal Fernando <ni...@gmail.com>
> wrote:
>
>> Thanks guys for the pointers. I'll create Jiras for all of these.
>>
>> On Mon, Oct 6, 2014 at 12:00 AM, Isuru Perera <is...@wso2.com> wrote:
>>
>>> I also agree with all points.
>>>
>>> On Sun, Oct 5, 2014 at 11:09 PM, Akila Ravihansa Perera <
>>> ravihansa@wso2.com> wrote:
>>>
>>>> Hi,
>>>>
>>>> +1 for all the suggested points.
>>>>
>>>> I would like to add few more to the list to be considered.
>>>>
>>>> 1. Provide useful error messages for back-end API exceptions.
>>>>
>>>> 2. Use of snake_case instead of camelCase in APIs. It is much more
>>>> readable.
>>>>
>>>
>> Do you have any concrete cases where people have used snake-case? I found
>> Google Kubernetes API is also using camel case:
>> http://cdn.rawgit.com/GoogleCloudPlatform/kubernetes/31a0daae3627c91bc96e1f02a6344cd76e294791/api/kubernetes.html
>>
>>>
>>>> 3. Support gzip compression.
>>>>
>>>> 4. Enable Cross-site Resource Sharing. We cannot make an API call to
>>>> Stratos REST API through Javascript without this.
>>>>
>>> +1. I also faced this issue and Stratos APIs were failing when invoking
>>> via an application using node.js/jQuery.
>>>
>>>>
>>>>
>>>>
>>>> On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <ni...@gmail.com>
>>>> wrote:
>>>> > All,
>>>> >
>>>> > Let's discuss how we could do $subject properly. AFAIS currently we
>>>> don't
>>>> > have any versioning in our REST API, but we have consumers of our
>>>> REST API.
>>>> >
>>>> > 1. We can make the default API version to be the latest version, i.e.
>>>> v2.
>>>> >
>>>> > So, if someone send a request to /<rootContext>/cartridges , it would
>>>> find
>>>> > /<rootContext>/v2/cartridges
>>>> >
>>>> > 2. Anyone can use the default API paths and still could request for a
>>>> > specific version via HTTP Accept Header.
>>>> >
>>>> > Accept: application/vnd.stratos.v1+json
>>>> >
>>>> >
>>>> > 3. Provide a migration guide for existing Clients.
>>>> >
>>>> > - If they want to use the old API, they need to specifically request
>>>> for the
>>>> > old API, by specifying the Accept header.
>>>> >
>>>> > 4. Mark v1 API as deprecated and announce that we'll remove the
>>>> support for
>>>> > it in the next release.
>>>> >
>>>> > Any other alternatives?
>>>> >
>>>> >
>>>> > --
>>>> > Best Regards,
>>>> > Nirmal
>>>> >
>>>> > Nirmal Fernando.
>>>> > PPMC Member & Committer of Apache Stratos,
>>>> > Senior Software Engineer, WSO2 Inc.
>>>> >
>>>> > Blog: http://nirmalfdo.blogspot.com/
>>>>
>>>>
>>>>
>>>> --
>>>> Akila Ravihansa Perera
>>>> Software Engineer, WSO2
>>>>
>>>> Blog: http://ravihansa3000.blogspot.com
>>>>
>>>
>>>
>>>
>>> --
>>> Isuru Perera
>>> Senior Software Engineer | WSO2, Inc. | http://wso2.com/
>>> Lean . Enterprise . Middleware
>>>
>>> about.me/chrishantha
>>>
>>
>>
>>
>> --
>> Best Regards,
>> Nirmal
>>
>> Nirmal Fernando.
>> PPMC Member & Committer of Apache Stratos,
>> Senior Software Engineer, WSO2 Inc.
>>
>> Blog: http://nirmalfdo.blogspot.com/
>>
>
>
>
> --
> Best Regards,
>
> Gayan Gunarathne
> Technical Lead
> WSO2 Inc. (http://wso2.com)
> email  : gayang@wso2.com  | mobile : +94 766819985
>
>



-- 
*Dinesh Bandara*
Software Engineer
WSO2 Inc.; http://wso2.com
lean.enterprise.middleware

Fwd: Versioning Stratos REST API

Posted by Gayan Gunarathne <ga...@wso2.com>.
I think camelcase is better as we are using java for developed the REST
API.I guess lot of APIs use this as they following naming conventions of
the underlying language they are using.Also there are some arguments that
snake-case will improve the readability , it may help when documentation
and samples.But again it will be conflict with our underline naming
convention. WDYT?

Thanks,
Gayan

On Mon, Oct 6, 2014 at 7:32 AM, Nirmal Fernando <ni...@gmail.com>
wrote:

> Thanks guys for the pointers. I'll create Jiras for all of these.
>
> On Mon, Oct 6, 2014 at 12:00 AM, Isuru Perera <is...@wso2.com> wrote:
>
>> I also agree with all points.
>>
>> On Sun, Oct 5, 2014 at 11:09 PM, Akila Ravihansa Perera <
>> ravihansa@wso2.com> wrote:
>>
>>> Hi,
>>>
>>> +1 for all the suggested points.
>>>
>>> I would like to add few more to the list to be considered.
>>>
>>> 1. Provide useful error messages for back-end API exceptions.
>>>
>>> 2. Use of snake_case instead of camelCase in APIs. It is much more
>>> readable.
>>>
>>
> Do you have any concrete cases where people have used snake-case? I found
> Google Kubernetes API is also using camel case:
> http://cdn.rawgit.com/GoogleCloudPlatform/kubernetes/31a0daae3627c91bc96e1f02a6344cd76e294791/api/kubernetes.html
>
>>
>>> 3. Support gzip compression.
>>>
>>> 4. Enable Cross-site Resource Sharing. We cannot make an API call to
>>> Stratos REST API through Javascript without this.
>>>
>> +1. I also faced this issue and Stratos APIs were failing when invoking
>> via an application using node.js/jQuery.
>>
>>>
>>>
>>>
>>> On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <ni...@gmail.com>
>>> wrote:
>>> > All,
>>> >
>>> > Let's discuss how we could do $subject properly. AFAIS currently we
>>> don't
>>> > have any versioning in our REST API, but we have consumers of our REST
>>> API.
>>> >
>>> > 1. We can make the default API version to be the latest version, i.e.
>>> v2.
>>> >
>>> > So, if someone send a request to /<rootContext>/cartridges , it would
>>> find
>>> > /<rootContext>/v2/cartridges
>>> >
>>> > 2. Anyone can use the default API paths and still could request for a
>>> > specific version via HTTP Accept Header.
>>> >
>>> > Accept: application/vnd.stratos.v1+json
>>> >
>>> >
>>> > 3. Provide a migration guide for existing Clients.
>>> >
>>> > - If they want to use the old API, they need to specifically request
>>> for the
>>> > old API, by specifying the Accept header.
>>> >
>>> > 4. Mark v1 API as deprecated and announce that we'll remove the
>>> support for
>>> > it in the next release.
>>> >
>>> > Any other alternatives?
>>> >
>>> >
>>> > --
>>> > Best Regards,
>>> > Nirmal
>>> >
>>> > Nirmal Fernando.
>>> > PPMC Member & Committer of Apache Stratos,
>>> > Senior Software Engineer, WSO2 Inc.
>>> >
>>> > Blog: http://nirmalfdo.blogspot.com/
>>>
>>>
>>>
>>> --
>>> Akila Ravihansa Perera
>>> Software Engineer, WSO2
>>>
>>> Blog: http://ravihansa3000.blogspot.com
>>>
>>
>>
>>
>> --
>> Isuru Perera
>> Senior Software Engineer | WSO2, Inc. | http://wso2.com/
>> Lean . Enterprise . Middleware
>>
>> about.me/chrishantha
>>
>
>
>
> --
> Best Regards,
> Nirmal
>
> Nirmal Fernando.
> PPMC Member & Committer of Apache Stratos,
> Senior Software Engineer, WSO2 Inc.
>
> Blog: http://nirmalfdo.blogspot.com/
>



-- 
Best Regards,

Gayan Gunarathne
Technical Lead
WSO2 Inc. (http://wso2.com)
email  : gayang@wso2.com  | mobile : +94 766819985

Re: Versioning Stratos REST API

Posted by Nirmal Fernando <ni...@gmail.com>.
Thanks guys for the pointers. I'll create Jiras for all of these.

On Mon, Oct 6, 2014 at 12:00 AM, Isuru Perera <is...@wso2.com> wrote:

> I also agree with all points.
>
> On Sun, Oct 5, 2014 at 11:09 PM, Akila Ravihansa Perera <
> ravihansa@wso2.com> wrote:
>
>> Hi,
>>
>> +1 for all the suggested points.
>>
>> I would like to add few more to the list to be considered.
>>
>> 1. Provide useful error messages for back-end API exceptions.
>>
>> 2. Use of snake_case instead of camelCase in APIs. It is much more
>> readable.
>>
>
Do you have any concrete cases where people have used snake-case? I found
Google Kubernetes API is also using camel case:
http://cdn.rawgit.com/GoogleCloudPlatform/kubernetes/31a0daae3627c91bc96e1f02a6344cd76e294791/api/kubernetes.html

>
>> 3. Support gzip compression.
>>
>> 4. Enable Cross-site Resource Sharing. We cannot make an API call to
>> Stratos REST API through Javascript without this.
>>
> +1. I also faced this issue and Stratos APIs were failing when invoking
> via an application using node.js/jQuery.
>
>>
>>
>>
>> On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <ni...@gmail.com>
>> wrote:
>> > All,
>> >
>> > Let's discuss how we could do $subject properly. AFAIS currently we
>> don't
>> > have any versioning in our REST API, but we have consumers of our REST
>> API.
>> >
>> > 1. We can make the default API version to be the latest version, i.e.
>> v2.
>> >
>> > So, if someone send a request to /<rootContext>/cartridges , it would
>> find
>> > /<rootContext>/v2/cartridges
>> >
>> > 2. Anyone can use the default API paths and still could request for a
>> > specific version via HTTP Accept Header.
>> >
>> > Accept: application/vnd.stratos.v1+json
>> >
>> >
>> > 3. Provide a migration guide for existing Clients.
>> >
>> > - If they want to use the old API, they need to specifically request
>> for the
>> > old API, by specifying the Accept header.
>> >
>> > 4. Mark v1 API as deprecated and announce that we'll remove the support
>> for
>> > it in the next release.
>> >
>> > Any other alternatives?
>> >
>> >
>> > --
>> > Best Regards,
>> > Nirmal
>> >
>> > Nirmal Fernando.
>> > PPMC Member & Committer of Apache Stratos,
>> > Senior Software Engineer, WSO2 Inc.
>> >
>> > Blog: http://nirmalfdo.blogspot.com/
>>
>>
>>
>> --
>> Akila Ravihansa Perera
>> Software Engineer, WSO2
>>
>> Blog: http://ravihansa3000.blogspot.com
>>
>
>
>
> --
> Isuru Perera
> Senior Software Engineer | WSO2, Inc. | http://wso2.com/
> Lean . Enterprise . Middleware
>
> about.me/chrishantha
>



-- 
Best Regards,
Nirmal

Nirmal Fernando.
PPMC Member & Committer of Apache Stratos,
Senior Software Engineer, WSO2 Inc.

Blog: http://nirmalfdo.blogspot.com/

Re: Versioning Stratos REST API

Posted by Isuru Perera <is...@wso2.com>.
I also agree with all points.

On Sun, Oct 5, 2014 at 11:09 PM, Akila Ravihansa Perera <ra...@wso2.com>
wrote:

> Hi,
>
> +1 for all the suggested points.
>
> I would like to add few more to the list to be considered.
>
> 1. Provide useful error messages for back-end API exceptions.
>
> 2. Use of snake_case instead of camelCase in APIs. It is much more
> readable.
>
> 3. Support gzip compression.
>
> 4. Enable Cross-site Resource Sharing. We cannot make an API call to
> Stratos REST API through Javascript without this.
>
+1. I also faced this issue and Stratos APIs were failing when invoking via
an application using node.js/jQuery.

>
>
>
> On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <ni...@gmail.com>
> wrote:
> > All,
> >
> > Let's discuss how we could do $subject properly. AFAIS currently we don't
> > have any versioning in our REST API, but we have consumers of our REST
> API.
> >
> > 1. We can make the default API version to be the latest version, i.e. v2.
> >
> > So, if someone send a request to /<rootContext>/cartridges , it would
> find
> > /<rootContext>/v2/cartridges
> >
> > 2. Anyone can use the default API paths and still could request for a
> > specific version via HTTP Accept Header.
> >
> > Accept: application/vnd.stratos.v1+json
> >
> >
> > 3. Provide a migration guide for existing Clients.
> >
> > - If they want to use the old API, they need to specifically request for
> the
> > old API, by specifying the Accept header.
> >
> > 4. Mark v1 API as deprecated and announce that we'll remove the support
> for
> > it in the next release.
> >
> > Any other alternatives?
> >
> >
> > --
> > Best Regards,
> > Nirmal
> >
> > Nirmal Fernando.
> > PPMC Member & Committer of Apache Stratos,
> > Senior Software Engineer, WSO2 Inc.
> >
> > Blog: http://nirmalfdo.blogspot.com/
>
>
>
> --
> Akila Ravihansa Perera
> Software Engineer, WSO2
>
> Blog: http://ravihansa3000.blogspot.com
>



-- 
Isuru Perera
Senior Software Engineer | WSO2, Inc. | http://wso2.com/
Lean . Enterprise . Middleware

about.me/chrishantha

Re: Versioning Stratos REST API

Posted by Akila Ravihansa Perera <ra...@wso2.com>.
Hi,

+1 for all the suggested points.

I would like to add few more to the list to be considered.

1. Provide useful error messages for back-end API exceptions.

2. Use of snake_case instead of camelCase in APIs. It is much more readable.

3. Support gzip compression.

4. Enable Cross-site Resource Sharing. We cannot make an API call to
Stratos REST API through Javascript without this.



On Sun, Oct 5, 2014 at 9:27 PM, Nirmal Fernando <ni...@gmail.com> wrote:
> All,
>
> Let's discuss how we could do $subject properly. AFAIS currently we don't
> have any versioning in our REST API, but we have consumers of our REST API.
>
> 1. We can make the default API version to be the latest version, i.e. v2.
>
> So, if someone send a request to /<rootContext>/cartridges , it would find
> /<rootContext>/v2/cartridges
>
> 2. Anyone can use the default API paths and still could request for a
> specific version via HTTP Accept Header.
>
> Accept: application/vnd.stratos.v1+json
>
>
> 3. Provide a migration guide for existing Clients.
>
> - If they want to use the old API, they need to specifically request for the
> old API, by specifying the Accept header.
>
> 4. Mark v1 API as deprecated and announce that we'll remove the support for
> it in the next release.
>
> Any other alternatives?
>
>
> --
> Best Regards,
> Nirmal
>
> Nirmal Fernando.
> PPMC Member & Committer of Apache Stratos,
> Senior Software Engineer, WSO2 Inc.
>
> Blog: http://nirmalfdo.blogspot.com/



-- 
Akila Ravihansa Perera
Software Engineer, WSO2

Blog: http://ravihansa3000.blogspot.com