| Item |
Section |
Comment |
Response |
| KP1 |
4.1 |
"...constitutes new API for GlassFish administration in addition to existing API's." You may want to clarify this. We should not provide a duplicate API implementation. You may want to write: The new REST interface (API) provides a unified mapping to existing GlassFish API's, and therefor can be thought of as a transport protocol to existing API's instead of an API layer itself. |
|
| KP2 |
4.1 |
"through adapter interface" - I think this should be "through a Grizzly Adapter"? |
|
| KP3 |
4.1 |
I am still unclear about the 2 "categories" of the HTTP interface ("configuration" and "monitoring"). The wording is better, but both state "...through HTTP urls" and do not explain the significance of dividing the interface. What is different? I suspect nothing. If this is the case, I recommend leaving out this grouping as it is artificial and will confuse people (Where does viewing a deployment descriptor fall? Deploying an application? Viewing a Log File?). If I write an extension for GlassFish, in which category do I put my new REST api's? |
|
| KP4 |
4.1.1 |
(NOTE: I like the short definitions you added for each of these here, thanks.) At least for the "Generic HTTP API", I strongly feel we should make this fully RESTful. In fact, we may ONLY want to expose the generic HTTP API and keep the CLI HTTP API private. |
|
| KP5 |
4.1.1.1 |
"using adapter interface" => "using the Grizzly Adapter interface" |
|
| KP6 |
4.1.1.1.1 |
URL format does not say that http*s* is available. Is this intentional? If not, please specify that this is possible: https://... This is required for the Admin Console. |
|
| KP7 |
4.1.1.1.1 |
It is unclear what request methods are supported. GET should not be supported for any command which alters the server (security violation). |
| KP8 |
4.1.1.1.1 |
While this may be the current URL format, I think it should be changed. 1. {extension} – This does not belong in the URL. This should be specified in a request header. (Accept header? And/or possibly a custom header.) 2. {command parameters} – These should be renamed to QUERY_STRING and should follow HTTP specifications for a QS: name1=value1&name2=value2&... 3. Things like "help" should be represented something like: <pre>https://{host}:{port}/_asadmin/help/{command}</pre> 4. Action should inferred based on GET (read) / PUT (update,create) / POST (create) / DELETE (delete) when possible (list actions should be a GET on a collection object). |
|
| KP9 |
4.1.1.1.2 |
In these particular examples it was unclear to me how to specify the "configuration" to be used. If there are multiple configurations, how do I pick the one I want? |
|
| KP10 |
4.1.1.1.2 |
*Example 1:* "http://localhost:port/_asadmin/list-http-listeners" should be: <pre>GET /_asadmin/http-listeners HTTP/1.1 accept: text/xml</pre> |
|
| KP11 |
4.1.1.1.2 |
*Example 2:* "http://localhost:port/_asadmin/list-http-listeners.json" should be: <pre>GET /_asadmin/http-listeners HTTP/1.1 accept: application/json |
|
| KP12 |
4.1.1.1.2 |
Example 3: Did not specify the url change necessary to get the additional output. |
|
| KP13 |
4.1.1.1.2 |
Example 3: 0.0.0.0 is not a valid number, it is a String and should be "0.0.0.0" (in quotes) |
|
| KP14 |
4.1.1.2.1 |
JSON format: {attributes} is not sufficiently specified. Arrays ([]'s) should be supported, as well as nested objects. I would suggest referring to (http:--en.wikipedia.org-wiki-Json) or better yet (http://www.json.org/). If some of that is NOT supported, it should be stated. |
|
| KP15 |
4.1.1.2.1 |
How much control over this object does a 3rd party add-on have? The content of {attributes} and values only? Part of those content areas? The entire response String? |
|
| KP16 |
4.1.1.2.1 |
XML format: How are more complicated objects represented, such as log records? |
|
| KP17 |
4.1.1.2.1 |
HTML format: Instead of using <h2>, etc (or in addition to), you should provide CSS classes (i.e. class="foo"), this will help people style this content. |
|
| KP18 |
4.1.1.2.2 |
Link to CLI spec should be to the Path spec, I think the correct URL is: https://glassfish.java.net/nonav/v3/admin/planning/V3Changes/V3_Pathnames.html (confirm with Lloyd) |
|
| KP19 |
4.1.1.2.2 |
https must be supported for the admin console (or any other client) to securely access the server |
|
| KP20 |
4.1.1.2.2 |
I would like to see a discussion in this document on how to map AMX object names to these paths and a commitment to support a predictable mapping back and forth between the 2. |
|
| KP21 |
4.1.1.2.2 |
I noticed that "_management" instead of "_asadmin" is used in these urls, I'm not sure if we should have 2 different mappings as it may not make sense to an end user. Although if _asadmin commands are private, this may make sense. |
|
| KP22 |
4.1.1.2.2 |
Please talk to Lloyd to ensure the alternate characters '/' or otherwise do not introduce any ambiguity. I believe '/' in place of []'s and maybe @ will introduce problems. I think ()'s may be a better substitution. After studying http:--www.faqs.org-rfcs-rfc1738.html, I think we can use @ in the PATH_INFO area of a URL w/o any problems, especially if we specify its purpose in our REST URLs. |
|
| KP23 |
4.1.1.2.2.1 |
Elaborate on "meta-data", even if you're still unsure of what meta-data will be supported. Give examples of what it "might" contain: data types, operations, description, etc. |
|
| KP24 |
4.1.1.2.3 |
Output (JSON): 0.0.0.0 -> "0.0.0.0" |
|
| KP25 |
4.1.1.2.3 |
Output (JSON), inside "resources" value: http:// ... -> "http://..." |
|
| KP26 |
4.1.1.2.3 |
It appears that all content besides simple attribute values require a separate request. This is not ideal. I would like objects to be returned instead of URLs to objects. |
|
| KP27 |
4.1.1.2.3 |
Full urls with host/port should not appear in the data. In the case of http browsers, they infer this from the current document (therefor overcoming proxy and other problems introduced by the server returning full urls). Other clients are capable of doing the same more effectively than the server. |
|
| KP28 |
4.1.1.2.3 |
I like that LIST is removed and you are using GET now, question, is Example 2 targeting a List/array type of object, or are you just implicitly returning the children of an object? I suggest only supporting the former to avoid the confusion of returning an Object vs. a List of Objects. |
|
| KP29 |
4.1.2.1 |
Please show URLs for examples 1 and 2. |
|
| KP30 |
4.1.2.1 |
Minor typo: Missing quotes around xyz in JSON examples 1 and 2. |
|
| KP31 |
4.1.2.1 |
HTML Output: I suggest using CSS classes instead of (or in addition to) H1/H2/etc. (not very important, but might be nice) |
|
| KP32 |
4.1.2.2 |
https is required. |
|
| KP33 |
4.1.2.2 |
Are QUERY_STRINGs supported? I suspect yes, it should be listed. |
|
| KP34 |
4.4 |
Scope of this document should be for v3 Final (not just what we can do by JavaOne) |
|
| KP35 |
4.4 |
Role-based authentication will probably be required for v3 final |
|
| KP36 |
4.4 |
HTTP/1.1 does support multiple requests in a single connection. I believe this is easily done via Grizzly as well, this should be easy to support with little or no effort. |
|
| KP37 |
4.4 |
Notifications via long requests (comet) should be supported at least by v3 final. |
|
| KP38 |
4.9 |
I18N/L10N support should be in place by v3 final (is this what you mean by next release?) |
|
| KP39 |
4.10 |
I suspect new commands generic and CLI will become available via 3rd party add-ons as well, which implies that some part of those commands are bundled with the plugins? |
|
| KP40 |
4.11 |
The admin console needs a solution which is more robust. Perhaps some certificate-based trust relationship with the client (admin console process) and the server? I am not sure what the best solution is here, but username/password is not a good option as we should not gather / maintain the password for the user (especially in clear text) |
|
| KP41 |
N/A |
We may need support for Push (comet) calls. Sreeni and Prashanth intend to communicate via comet with us as well. This gives us multiple access points for us to connect to the same host, which presents a problem since some browsers only allow 2 connections to the same server. They also must solve security and authentication issues. I think it would be worth working together to come up with a common re-usable solution which solves these problems. |
|
| KP42 |
N/A |
I think we should attempt to make the "generic HTTP API" truly RESTful. If this is not possible, we should document the reasons why it is not possible so we can work toward overcoming them in a future release. I do not see anything obvious that is preventing us from being REST compliant. |
|
