GlassFish Wiki : V3HTTPInterfacesReviewJasonLee

GlassFish HTTP/REST API Interfaces Review

Document: GlassFish v3 HTTP/REST Interfaces One Pager

Reviewer: Jason Lee

Review date:

Response date:

Item	Section	Comment	Response
Project Description	2.1	I'd like to replace "like" with "full." I'd really prefer that we have a fully RESTful interface, making proper use of the "standard" semantics for the various HTTP verbs. If we're just "RESTlike," my guess is that the dissimilarities with "real" REST will prove to be a real sore spot with third party developers. I think a fully RESTful interface will help us in terms of developer adoption, as well as politically.
Command Line HTTP API	4.1.1.1	I tend to agree with some of Ken's statements here, especially with regard to the extension and method. As Ken noted, specifying the method here is a pretty big security hole and violates the nature of REST, which determines the operation based on the verb used in the request. For the extension, I like Ken's suggestion of the request header. That keeps the URL clean, and (I apologize if you're tired of hearing this drum) seems more RESTful. If the request header is not specified, HTML seems like a proper response type to fall back to. This would let an admin punch in the URL for a quick and dirty check on something, for example. I'm also not just real excited about the proposed URL. In example 1, to get a list of http-listeners, you have http://localhost:port/__asadmin/list-http-listeners. I think Ken hit on this, but I'll say it here too. I think that should just be http://localhost:port/__asadmin/http-listeners with the GET request returning the list of http-listeners. To see a particular http-listener, the URL would be something http://localhost:port/__asadmin/http-listener/http-listener-1 (again, as a GET for the view).
Some examples of Generic HTTP API	4.1.1.2.3	There are no examples of POST/PUT requests and their payload. That really needs to be specified or discussed (even if the input is merely a parroting of a modified GET return)