Restlet API evolution - Conversion between Throwable & HTTP status+body

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Restlet API evolution - Conversion between Throwable & HTTP status+body

Jerome Louvel-3
Hi all,

In V2.3 of Restlet API, we would like to introduce automatic conversion between Java throwable and HTTP status+body, working both ways (client and server sides).

The goal is to be able to write annotated Java interfaces including methods such as:
 @Get
 public MyBean represent() throws MyServerError, MyNotFoundError;
Were the MyServerError and MyNotFoundError could be serialized as JSON/XML/eetc. error representations. For this you would annotate those Throwable classes with a @Status annotation such as:
 @Status("500")
 public class MyServerError implements Throwable{
    ...
 }
 
 @Status("404")
 public class MyNotFoundError extends RuntimeException{
    ...
 }
A ClientResource wrapped proxy of MyResource including the represent() method would automatically deserialize the error JSON/XML/etc. into the proper Java exception.

A ServerResource implementing the MyResource would be able to directly throw a MyServerError or a MyNotFoundError, setting its properties without having to worry about the HTTP status and error body. Content negotiation would even be able to take place.

Would that be useful in your web APIs? Any design feed-back?


Reply | Threaded
Open this post in threaded view
|

Re: Restlet API evolution - Conversion between Throwable & HTTP status+body

Fabian Mandelbaum
I like the idea.

Some comments:

1) There's some statuses that do not allow for a response body, IIRC HTTP 204. How would you handle that? Compile-time error? Other checks?

2) If for any reason, my server resource class redefines one of those exceptions, how would this be handled? I'd expect the one redefined on my server resource is used...

May add more comments/ideas later...

Thanks.



On Thu, Jun 5, 2014 at 7:20 PM, Jerome Louvel <[hidden email]> wrote:
Hi all,

In V2.3 of Restlet API, we would like to introduce automatic conversion between Java throwable and HTTP status+body, working both ways (client and server sides).

The goal is to be able to write annotated Java interfaces including methods such as:
 @Get
 public MyBean represent() throws MyServerError, MyNotFoundError;
Were the MyServerError and MyNotFoundError could be serialized as JSON/XML/eetc. error representations. For this you would annotate those Throwable classes with a @Status annotation such as:
 @Status("500")
 public class MyServerError implements Throwable{
    ...
 }
 
 @Status("404")
 public class MyNotFoundError extends RuntimeException{
    ...
 }
A ClientResource wrapped proxy of MyResource including the represent() method would automatically deserialize the error JSON/XML/etc. into the proper Java exception.

A ServerResource implementing the MyResource would be able to directly throw a MyServerError or a MyNotFoundError, setting its properties without having to worry about the HTTP status and error body. Content negotiation would even be able to take place.

Would that be useful in your web APIs? Any design feed-back?





--
Fabián Mandelbaum
IS Engineer
Reply | Threaded
Open this post in threaded view
|

Re: Restlet API evolution - Conversion between Throwable & HTTP status+body

Jerome Louvel-3
Thanks Fabian for the feed-back.

1) We would not set the response entity in this case, only the HTTP status would be set on the response based on the annotation value.

2) I'm not 100% clear about the scenario. Let me try some replies:

  a) if you do not throw any exception and manually set an error status and response entity, then it would take precedence

  b) the goal is for your resource classes to actually define those exceptions and ensure they are automatically handled at run-time.

  c) we might want to offer some generic exceptions such as NotFoundException<T> based on @Status for main HTTP status codes that would let you override them to specify a custom <T> bean to serialize as response entity but the HTTP status code would be automatically set.




On Thu, Jun 5, 2014 at 3:52 PM, Fabian Mandelbaum <[hidden email]> wrote:
I like the idea.

Some comments:

1) There's some statuses that do not allow for a response body, IIRC HTTP 204. How would you handle that? Compile-time error? Other checks?

2) If for any reason, my server resource class redefines one of those exceptions, how would this be handled? I'd expect the one redefined on my server resource is used...

May add more comments/ideas later...

Thanks.



On Thu, Jun 5, 2014 at 7:20 PM, Jerome Louvel <[hidden email]> wrote:
Hi all,

In V2.3 of Restlet API, we would like to introduce automatic conversion between Java throwable and HTTP status+body, working both ways (client and server sides).

The goal is to be able to write annotated Java interfaces including methods such as:
 @Get
 public MyBean represent() throws MyServerError, MyNotFoundError;
Were the MyServerError and MyNotFoundError could be serialized as JSON/XML/eetc. error representations. For this you would annotate those Throwable classes with a @Status annotation such as:
 @Status("500")
 public class MyServerError implements Throwable{
    ...
 }
 
 @Status("404")
 public class MyNotFoundError extends RuntimeException{
    ...
 }
A ClientResource wrapped proxy of MyResource including the represent() method would automatically deserialize the error JSON/XML/etc. into the proper Java exception.

A ServerResource implementing the MyResource would be able to directly throw a MyServerError or a MyNotFoundError, setting its properties without having to worry about the HTTP status and error body. Content negotiation would even be able to take place.

Would that be useful in your web APIs? Any design feed-back?





--
Fabián Mandelbaum
IS Engineer

Reply | Threaded
Open this post in threaded view
|

Re: Restlet API evolution - Conversion between Throwable & HTTP status+body

Fabian Mandelbaum
Hello Jerome, answering between lines:


On Thu, Jun 5, 2014 at 8:15 PM, Jerome Louvel <[hidden email]> wrote:
Thanks Fabian for the feed-back.

1) We would not set the response entity in this case, only the HTTP status would be set on the response based on the annotation value.


OK

 
2) I'm not 100% clear about the scenario. Let me try some replies:

  a) if you do not throw any exception and manually set an error status and response entity, then it would take precedence

  b) the goal is for your resource classes to actually define those exceptions and ensure they are automatically handled at run-time.

  c) we might want to offer some generic exceptions such as NotFoundException<T> based on @Status for main HTTP status codes that would let you override them to specify a custom <T> bean to serialize as response entity but the HTTP status code would be automatically set.


Well, a) and c) (mostly c) is what I had in mind, so we agree :-)
 
Thanks,

My pleasure.
 


On Thu, Jun 5, 2014 at 3:52 PM, Fabian Mandelbaum <[hidden email]> wrote:
I like the idea.

Some comments:

1) There's some statuses that do not allow for a response body, IIRC HTTP 204. How would you handle that? Compile-time error? Other checks?

2) If for any reason, my server resource class redefines one of those exceptions, how would this be handled? I'd expect the one redefined on my server resource is used...

May add more comments/ideas later...

Thanks.



On Thu, Jun 5, 2014 at 7:20 PM, Jerome Louvel <[hidden email]> wrote:
Hi all,

In V2.3 of Restlet API, we would like to introduce automatic conversion between Java throwable and HTTP status+body, working both ways (client and server sides).

The goal is to be able to write annotated Java interfaces including methods such as:
 @Get
 public MyBean represent() throws MyServerError, MyNotFoundError;
Were the MyServerError and MyNotFoundError could be serialized as JSON/XML/eetc. error representations. For this you would annotate those Throwable classes with a @Status annotation such as:
 @Status("500")
 public class MyServerError implements Throwable{
    ...
 }
 
 @Status("404")
 public class MyNotFoundError extends RuntimeException{
    ...
 }
A ClientResource wrapped proxy of MyResource including the represent() method would automatically deserialize the error JSON/XML/etc. into the proper Java exception.

A ServerResource implementing the MyResource would be able to directly throw a MyServerError or a MyNotFoundError, setting its properties without having to worry about the HTTP status and error body. Content negotiation would even be able to take place.

Would that be useful in your web APIs? Any design feed-back?





--
Fabián Mandelbaum
IS Engineer




--
Fabián Mandelbaum
IS Engineer
Reply | Threaded
Open this post in threaded view
|

Re: Restlet API evolution - Conversion between Throwable & HTTP status+body

Ralph van Etten
In reply to this post by Jerome Louvel-3
Hi all,


On 06/06/2014 12:20 AM, Jerome Louvel wrote:
> Hi all,
>
> In V2.3 of Restlet API, we would like to introduce automatic conversion
> between Java throwable and HTTP status+body, working both ways (client
> and server sides).
>
...
>
> Would that be useful in your web APIs? Any design feed-back?

Yes, that would be very useful.
In fact, I am already doing something similar.

I have put similar annotations on my exceptions. In the doCatch() of my
ServerResource I process those annotations and send a JSON document
containing error details to the client. The client then uses the
information in the JSON document and converts it to the same exception.

On the server side this works fine but my client implementation is not
as good as you are describing. Similar functionality provided by Restlet
would be very welcome.


Regards,

Ralph van Etten

------------------------------------------------------
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=3079995
Reply | Threaded
Open this post in threaded view
|

Re: Restlet API evolution - Conversion between Throwable & HTTP status+body

Jerome Louvel-3
Hi all,

FYI, the @Status annotation has indeed been added in Restlet API v2.3 and works on both server and client side as discussed in this thread. 

Thanks,
Jerome


On Fri, Jun 6, 2014 at 3:55 AM, Ralph van Etten <[hidden email]> wrote:
Hi all,


On 06/06/2014 12:20 AM, Jerome Louvel wrote:
> Hi all,
>
> In V2.3 of Restlet API, we would like to introduce automatic conversion
> between Java throwable and HTTP status+body, working both ways (client
> and server sides).
>
...
>
> Would that be useful in your web APIs? Any design feed-back?

Yes, that would be very useful.
In fact, I am already doing something similar.

I have put similar annotations on my exceptions. In the doCatch() of my
ServerResource I process those annotations and send a JSON document
containing error details to the client. The client then uses the
information in the JSON document and converts it to the same exception.

On the server side this works fine but my client implementation is not
as good as you are describing. Similar functionality provided by Restlet
would be very welcome.


Regards,

Ralph van Etten

------------------------------------------------------
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=3079995