You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@stratos.apache.org by Dinithi De Silva <di...@wso2.com> on 2015/04/22 07:45:14 UTC
Re-factoring REST API
Hi all,
We are in the process of re-factoring the REST API with the following
changes (As discussed in a separate mail thread - [Discuss] REST API
Improvements ).
1. *Moving non-API methods to StratosApiV41Utils class from **StratosApiV41
class*. (Refer the mail thread - API methods for tenants)
2. *Re-factoring the response message according to the below structure.*
(Refer the mail thread - [Question] Is is correct for two different status
codes appear when adding a tenant?)
Currently we are using two bean classes for success response and error
response. After this modification there will be only one unified response
bean.
{
"status":"successful",
"message":"Application A1 created successfully"
}
{
"status":"error",
"message":"An application with the id A1 already exists"
}
3. *Using a small range of status codes to improve the user experience
and also resolving issues in status codes.* (Refer the mail thread - [Discuss]
REST API Improvements)
So the 209 - No Content status code will be removed and the following will
be used.
- *200 OK* - GET, DELETE (with content body), PUT - Success
- *201 Created* - POST - Resource Created, send Location header
- *202 Accepted* - Used in application deployment and undeployment
- *404 Not Found* - GET, POST, PUT, DELETE
- *409 Conflict* - POST, PUT - Resource being added already exists
- *400 Bad Request* - Other request error (only)
- *500 Internal Server Error* - Error is server side
4.* Resolving problems in exception throwing and validating requests. *(Refer
the mail thread - [Discuss] REST API Improvements)
Currently when a server side exception is caught, it always throws a
RestAPIExceptions.
This should be modified to throw custom exceptions when needed.
Also the CLI and the UI will be changed according to these modifications.
Please feel free to add your comments if I am missing something here.
--
*Dinithi De Silva*
Associate Software Engineer, WSO2 Inc.
m:+94716667655 | e:dinithis@wso2.com | w: www.wso2.com
| a: #20, Palm Grove, Colombo 03
RE: Re-factoring REST API
Posted by "Shaheedur Haque (shahhaqu)" <sh...@cisco.com>.
Thanks for clarifying. In the case of the 500, is it possible to expose the causing error instead of “internal server error”? Or at least “internal server error: <cause>”?
From: Dinithi De Silva [mailto:dinithis@wso2.com]
Sent: 23 April 2015 12:16
To: Shaheedur Haque (shahhaqu)
Cc: dev; Vanson Lim (vlim); Martin Eppel (meppel); Imesh Gunaratne
Subject: Re: Re-factoring REST API
Hi,
This modification will expose the error status as 400 bad request, 404 not found or 500 internal server error other than sending 400 bad request for every server-side error.
Thanks.
On Thu, Apr 23, 2015 at 2:24 PM, Shaheedur Haque (shahhaqu) <sh...@cisco.com>> wrote:
In general, this is an excellent idea. (We may have a small adaptation to make on our side when this lands, but it will be worth it).
Will the effect of moving away from the RestApiException be to expose the underlying error? What would that look like in JSON terms?
From: Dinithi De Silva [mailto:dinithis@wso2.com<ma...@wso2.com>]
Sent: 23 April 2015 09:48
To: dev
Cc: Vanson Lim (vlim); Shaheedur Haque (shahhaqu); Martin Eppel (meppel); Imesh Gunaratne
Subject: Re: Re-factoring REST API
Hi,
I have listed the changes in a point form below.
* In all the API methods the response message format will be changed to display a status message either with "Success" or "Error" . Status code will be removed from the response message.
Eg:
Current format
return Response.status(Response.Status.CONFLICT).entity(new ErrorResponseBean(Response.Status.CONFLICT.getStatusCode(), msg)).build();
After the modifications
return Response.status(Response.Status.CONFLICT).entity(new StatusResponseBean(Constants.STATUS_ERROR, msg)).build();
* The following non API methods found in StratosAPIV41 class will be moved to the StratosAPIV41Util class.
activateTenant(String)
addTenant(TenantInfoBean)
deactivateTenant(String)
getPartialSearchTenants(String)
getTenantForDomain(String)
getTenants()
removeTenant(String)
updateTenant(TenantInfoBean)
addUser(UserInfoBean)
getUsers()
removeUser(String)
updateUser(UserInfoBean)
* Removing 204 NO_CONTENT status code
204 NO_CONTENT status code will be removed from removeKubernetesHostCluster API method.
* Resolving problems in exception throwing and validating requests.
In this modifications we plan to give custom exceptions when needed other than throwing RestAPIException.
Thank you
--
Dinithi De Silva
Associate Software Engineer, WSO2 Inc.
m:+94716667655<tel:%2B94716667655> | e:dinithis@wso2.com<ma...@wso2.com> | w: www.wso2.com<http://www.wso2.com>
| a: #20, Palm Grove, Colombo 03
--
Dinithi De Silva
Associate Software Engineer, WSO2 Inc.
m:+94716667655 | e:dinithis@wso2.com<ma...@wso2.com> | w: www.wso2.com<http://www.wso2.com>
| a: #20, Palm Grove, Colombo 03
Re: Re-factoring REST API
Posted by Dinithi De Silva <di...@wso2.com>.
Hi,
This modification will expose the error status as 400 bad request, 404 not
found or 500 internal server error other than sending 400 bad request for
every server-side error.
Thanks.
On Thu, Apr 23, 2015 at 2:24 PM, Shaheedur Haque (shahhaqu) <
shahhaqu@cisco.com> wrote:
> In general, this is an excellent idea. (We may have a small adaptation
> to make on our side when this lands, but it will be worth it).
>
>
>
> Will the effect of moving away from the RestApiException be to expose the
> underlying error? What would that look like in JSON terms?
>
>
>
> *From:* Dinithi De Silva [mailto:dinithis@wso2.com]
> *Sent:* 23 April 2015 09:48
> *To:* dev
> *Cc:* Vanson Lim (vlim); Shaheedur Haque (shahhaqu); Martin Eppel
> (meppel); Imesh Gunaratne
> *Subject:* Re: Re-factoring REST API
>
>
>
> Hi,
>
>
>
> I have listed the changes in a point form below.
>
>
>
> - *In all the API methods the response message format will be changed
> to display a status message either with "Success" or "Error" . Status code
> will be removed from the response message.*
>
> Eg:
>
>
>
> *Current format*
>
> return Response.status(Response.Status.CONFLICT).entity(new
> ErrorResponseBean(Response.Status.CONFLICT.getStatusCode(), msg)).build();
>
>
>
> *After the modifications*
>
> return Response.status(Response.Status.CONFLICT).entity(new
> StatusResponseBean(Constants.STATUS_ERROR, msg)).build();
>
>
>
>
>
> - *The following non API methods found in **StratosAPIV41 class will
> be moved to the **StratosAPIV41Util class.*
>
> activateTenant(String)
> addTenant(TenantInfoBean)
> deactivateTenant(String)
> getPartialSearchTenants(String)
> getTenantForDomain(String)
> getTenants()
> removeTenant(String)
> updateTenant(TenantInfoBean)
>
> addUser(UserInfoBean)
> getUsers()
> removeUser(String)
> updateUser(UserInfoBean)
>
>
>
> - *Removing 204 NO_CONTENT status code*
>
> 204 NO_CONTENT status code will be removed from *removeKubernetesHostCluster
> *API method*.*
>
>
>
> - *Resolving problems in exception throwing and validating requests.*
>
> In this modifications we plan to give custom exceptions when needed
> other than throwing RestAPIException.
>
>
>
>
>
> Thank you
>
>
>
> --
>
> *Dinithi De Silva*
> Associate Software Engineer, WSO2 Inc.
> m:+94716667655 | e:dinithis@wso2.com | w: www.wso2.com
> | a: #20, Palm Grove, Colombo 03
>
--
*Dinithi De Silva*
Associate Software Engineer, WSO2 Inc.
m:+94716667655 | e:dinithis@wso2.com | w: www.wso2.com
| a: #20, Palm Grove, Colombo 03
RE: Re-factoring REST API
Posted by "Shaheedur Haque (shahhaqu)" <sh...@cisco.com>.
In general, this is an excellent idea. (We may have a small adaptation to make on our side when this lands, but it will be worth it).
Will the effect of moving away from the RestApiException be to expose the underlying error? What would that look like in JSON terms?
From: Dinithi De Silva [mailto:dinithis@wso2.com]
Sent: 23 April 2015 09:48
To: dev
Cc: Vanson Lim (vlim); Shaheedur Haque (shahhaqu); Martin Eppel (meppel); Imesh Gunaratne
Subject: Re: Re-factoring REST API
Hi,
I have listed the changes in a point form below.
* In all the API methods the response message format will be changed to display a status message either with "Success" or "Error" . Status code will be removed from the response message.
Eg:
Current format
return Response.status(Response.Status.CONFLICT).entity(new ErrorResponseBean(Response.Status.CONFLICT.getStatusCode(), msg)).build();
After the modifications
return Response.status(Response.Status.CONFLICT).entity(new StatusResponseBean(Constants.STATUS_ERROR, msg)).build();
* The following non API methods found in StratosAPIV41 class will be moved to the StratosAPIV41Util class.
activateTenant(String)
addTenant(TenantInfoBean)
deactivateTenant(String)
getPartialSearchTenants(String)
getTenantForDomain(String)
getTenants()
removeTenant(String)
updateTenant(TenantInfoBean)
addUser(UserInfoBean)
getUsers()
removeUser(String)
updateUser(UserInfoBean)
* Removing 204 NO_CONTENT status code
204 NO_CONTENT status code will be removed from removeKubernetesHostCluster API method.
* Resolving problems in exception throwing and validating requests.
In this modifications we plan to give custom exceptions when needed other than throwing RestAPIException.
Thank you
--
Dinithi De Silva
Associate Software Engineer, WSO2 Inc.
m:+94716667655<tel:%2B94716667655> | e:dinithis@wso2.com<ma...@wso2.com> | w: www.wso2.com<http://www.wso2.com>
| a: #20, Palm Grove, Colombo 03
Re: Re-factoring REST API
Posted by Dinithi De Silva <di...@wso2.com>.
Hi,
I have listed the changes in a point form below.
- *In all the API methods the response message format will be changed to
display a status message either with "Success" or "Error" . Status code
will be removed from the response message.*
Eg:
*Current format*
return Response.status(Response.Status.CONFLICT).entity(new
ErrorResponseBean(Response.Status.CONFLICT.getStatusCode(), msg)).build();
*After the modifications*
return Response.status(Response.Status.CONFLICT).entity(new
StatusResponseBean(Constants.STATUS_ERROR, msg)).build();
- *The following non API methods found in StratosAPIV41 class will be
moved to the StratosAPIV41Util class.*
activateTenant(String)
addTenant(TenantInfoBean)
deactivateTenant(String)
getPartialSearchTenants(String)
getTenantForDomain(String)
getTenants()
removeTenant(String)
updateTenant(TenantInfoBean)
addUser(UserInfoBean)
getUsers()
removeUser(String)
updateUser(UserInfoBean)
- *Removing 204 NO_CONTENT status code*
204 NO_CONTENT status code will be removed from *removeKubernetesHostCluster
*API method*.*
- *Resolving problems in exception throwing and validating requests.*
In this modifications we plan to give custom exceptions when needed other
than throwing RestAPIException.
Thank you
--
*Dinithi De Silva*
Associate Software Engineer, WSO2 Inc.
m:+94716667655 | e:dinithis@wso2.com | w: www.wso2.com
| a: #20, Palm Grove, Colombo 03
Re: Re-factoring REST API
Posted by Imesh Gunaratne <im...@apache.org>.
Just to clarify we are only changing the HTTP status codes and response
message formats (of error and successful messages) in the REST API. We are
not changing any of the API method definitions or JSON definitions.
Dinithi: It would be great if you could list of out the changes in point
form.
Thanks
On Wed, Apr 22, 2015 at 11:26 AM, Anuruddha Liyanarachchi <
anuruddhal@wso2.com> wrote:
> Hi,
>
> Please find the list of current status codes that are being used [1].
>
> [1]
> https://docs.google.com/spreadsheets/d/1orFbcvkrowtz_LKJL7IXzQgBBxloMkFICobZGxlKMuA/edit?usp=sharing
>
> On Wed, Apr 22, 2015 at 11:15 AM, Dinithi De Silva <di...@wso2.com>
> wrote:
>
>> Hi all,
>>
>> We are in the process of re-factoring the REST API with the following
>> changes (As discussed in a separate mail thread - [Discuss] REST API
>> Improvements ).
>>
>> 1. *Moving non-API methods to StratosApiV41Utils class from **StratosApiV41
>> class*. (Refer the mail thread - API methods for tenants)
>>
>> 2. *Re-factoring the response message according to the below structure.*
>> (Refer the mail thread - [Question] Is is correct for two different status
>> codes appear when adding a tenant?)
>>
>> Currently we are using two bean classes for success response and error
>> response. After this modification there will be only one unified response
>> bean.
>>
>> {
>> "status":"successful",
>> "message":"Application A1 created successfully"
>> }
>>
>> {
>> "status":"error",
>> "message":"An application with the id A1 already exists"
>> }
>>
>> 3. *Using a small range of status codes to improve the user experience
>> and also resolving issues in status codes.* (Refer the mail thread - [Discuss]
>> REST API Improvements)
>>
>> So the 209 - No Content status code will be removed and the following
>> will be used.
>>
>> - *200 OK* - GET, DELETE (with content body), PUT - Success
>> - *201 Created* - POST - Resource Created, send Location header
>> - *202 Accepted* - Used in application deployment and undeployment
>> - *404 Not Found* - GET, POST, PUT, DELETE
>> - *409 Conflict* - POST, PUT - Resource being added already exists
>> - *400 Bad Request* - Other request error (only)
>> - *500 Internal Server Error* - Error is server side
>>
>>
>> 4.* Resolving problems in exception throwing and validating requests. *(Refer
>> the mail thread - [Discuss] REST API Improvements)
>>
>> Currently when a server side exception is caught, it always throws a RestAPIExceptions.
>> This should be modified to throw custom exceptions when needed.
>>
>> Also the CLI and the UI will be changed according to these modifications.
>>
>> Please feel free to add your comments if I am missing something here.
>>
>> --
>> *Dinithi De Silva*
>> Associate Software Engineer, WSO2 Inc.
>> m:+94716667655 | e:dinithis@wso2.com | w: www.wso2.com
>> | a: #20, Palm Grove, Colombo 03
>>
>
>
>
> --
> *Thanks and Regards,*
> Anuruddha Lanka Liyanarachchi
> Software Engineer - WSO2
> Mobile : +94 (0) 712762611
> Tel : +94 112 145 345
> a <th...@wso2.com>nuruddhal@wso2.com
>
--
Imesh Gunaratne
Technical Lead, WSO2
Committer & PMC Member, Apache Stratos
Re: Re-factoring REST API
Posted by Anuruddha Liyanarachchi <an...@wso2.com>.
Hi,
Please find the list of current status codes that are being used [1].
[1]
https://docs.google.com/spreadsheets/d/1orFbcvkrowtz_LKJL7IXzQgBBxloMkFICobZGxlKMuA/edit?usp=sharing
On Wed, Apr 22, 2015 at 11:15 AM, Dinithi De Silva <di...@wso2.com>
wrote:
> Hi all,
>
> We are in the process of re-factoring the REST API with the following
> changes (As discussed in a separate mail thread - [Discuss] REST API
> Improvements ).
>
> 1. *Moving non-API methods to StratosApiV41Utils class from **StratosApiV41
> class*. (Refer the mail thread - API methods for tenants)
>
> 2. *Re-factoring the response message according to the below structure.*
> (Refer the mail thread - [Question] Is is correct for two different status
> codes appear when adding a tenant?)
>
> Currently we are using two bean classes for success response and error
> response. After this modification there will be only one unified response
> bean.
>
> {
> "status":"successful",
> "message":"Application A1 created successfully"
> }
>
> {
> "status":"error",
> "message":"An application with the id A1 already exists"
> }
>
> 3. *Using a small range of status codes to improve the user experience
> and also resolving issues in status codes.* (Refer the mail thread - [Discuss]
> REST API Improvements)
>
> So the 209 - No Content status code will be removed and the following will
> be used.
>
> - *200 OK* - GET, DELETE (with content body), PUT - Success
> - *201 Created* - POST - Resource Created, send Location header
> - *202 Accepted* - Used in application deployment and undeployment
> - *404 Not Found* - GET, POST, PUT, DELETE
> - *409 Conflict* - POST, PUT - Resource being added already exists
> - *400 Bad Request* - Other request error (only)
> - *500 Internal Server Error* - Error is server side
>
>
> 4.* Resolving problems in exception throwing and validating requests. *(Refer
> the mail thread - [Discuss] REST API Improvements)
>
> Currently when a server side exception is caught, it always throws a RestAPIExceptions.
> This should be modified to throw custom exceptions when needed.
>
> Also the CLI and the UI will be changed according to these modifications.
>
> Please feel free to add your comments if I am missing something here.
>
> --
> *Dinithi De Silva*
> Associate Software Engineer, WSO2 Inc.
> m:+94716667655 | e:dinithis@wso2.com | w: www.wso2.com
> | a: #20, Palm Grove, Colombo 03
>
--
*Thanks and Regards,*
Anuruddha Lanka Liyanarachchi
Software Engineer - WSO2
Mobile : +94 (0) 712762611
Tel : +94 112 145 345
a <th...@wso2.com>nuruddhal@wso2.com