dev@glassfish.java.net

Re: spec for http admin api for v3?

From: Peter Williams <Pete.Williams_at_Sun.COM>
Date: Sat, 02 Feb 2008 00:54:00 -0800

Jane Young wrote:
> Hi Peter,
>
> Thanks for changing the subject of this e-mail. I was a bit confused
> earlier about what spec you are asking.
>
> Let me get this clear, you're asking for a list of CLI commands
> available in http url format?
> And you want to know what is the input/output of these commands?
> Input meaning how is "asadmin <command-name> <options> <operands>"
> translates to http url and the format of the url?
Certainly the URL format is needed, but the document I referenced
earlier already has that,

What I really meant --

Which commands are HTTP GET and which are HTTP PUT (if any) and in the
latter case, format of upload. Also POST or DELETE if used, of course.
What is the format of the data returned by a given HTTP command (when
user-agent = "hk2-agent", as I mentioned). For example,
list-applications returns data in java.util.jar.Manifest format.

-Peter
> Output meaning the output of "asadmin" and to the browser?
> If this is what you're asking, then yes, there will be a doc available
> and it will be updated by the authors of the commands.
> The wiki site:
> http://wiki.glassfish.java.net/Wiki.jsp?page=V3AdminCommands
> shows the commands that are currently supported in GFv3. As the admin
> team is ramping up their work in GFv3, you'll see the list of the
> commands increases.
>
> Let me know if this is what you're asking for.
>
> Thanks,
> Jane
>
>
>
> Ludovic Champenois wrote:
>
>> Peter Williams wrote:
>>
>>> Sorry for starting this. The name really had nothing to do with my
>>> original question.
>>>
>>> I agree the protocol is not particularly REST like in the regards
>>> already mentioned.
>>>
>>> Being similar or the same as CLI asadmin commands is probably more
>>> valuable for the familiarity than adhering strictly to design
>>> pattern, however useful that patten might be in it's own right.
>>>
>>> I changed header to "http admin api"...
>>
>>
>> Let's go back to the original intent of this thread.
>> Today, 2 leading IDEs (NetBeans 6.x and Eclipse 3.x) have GlassFish
>> V3 plugins that *do* rely on these URL apis to communicate to a V3
>> server.
>> So in a sense this is an exposed interface (maybe not stable, but
>> this is not the point).
>> We are using it, so please if this is going to change, we need to be
>> warned in advance.
>>
>> Thanks,
>> Ludo
>>
>>>
>>> -Peter
>>>
>>> Lloyd L Chambers wrote:
>>>
>>>> Well, perhaps let's not call it REST then.
>>>>
>>>> I think of it as a "command line in a browser". I LIKE the fact
>>>> that it is very similar to using the 'asadmin' CLI, including
>>>> identical command names and option names. I think it would be a
>>>> huge mistake to introduce an entirely new set of names for commands
>>>> and options.
>>>>
>>>> Lloyd
>>>>
>>>> On Feb 1, 2008, at 5:31 AM, Paul Sandoz wrote:
>>>>
>>>>> Jakub Podlesak wrote:
>>>>>
>>>>>> On Thu, Jan 31, 2008 at 07:25:01PM -0800, Peter Williams wrote:
>>>>>>
>>>>>>> Is there a document detailing the inputs & outputs for V3's REST
>>>>>>> api?
>>>>>>>
>>>>>>> I found the one here:
>>>>>>> http://wiki.glassfish.java.net/Wiki.jsp?page=V3AdminCommands
>>>>>>
>>>>>> the above described api doesn't look very RESTfully.
>>>>>> It uses verbs to specify methods in URIs. It is probably fine as
>>>>>> long as it is not called REST api.
>>>>>
>>>>>
>>>>> Agreed. Although from the documentation i don't think it makes any
>>>>> claims to be :-) Although i would strongly encourage that we make
>>>>> it a RESTful API.
>>>>>
>>>>> From this documentation it is not clear what the actual HTTP
>>>>> method is used with the URIs, GET or POST? if the former then it
>>>>> is very unRESTful and breaks the semantics of the HTTP GET method
>>>>> which should not have unintended side effects (imagine a web
>>>>> crawler traversing such URIs and unintentionally causing
>>>>> side-effects, or reloading the URI in a browser, or clicking in
>>>>> such a URI in a email message).
>>>>>
>>>>> IMHO i think it possible to create a nice RESTful API that is easy
>>>>> to use by both machines and browsers. We could even create some
>>>>> WADL for it and transform that to some nice documentation [1].
>>>>>
>>>>> For example:
>>>>>
>>>>> // get the list of applications
>>>>> // returns a list of URIs for each application
>>>>> // use query param to limit scope of list
>>>>> GET http://localhost:8080/__asadmin/applications
>>>>>
>>>>> // Deploy new application
>>>>> POST http://localhost:8080/__asadmin/applications
>>>>> // use application/x-www-form-urlencoded
>>>>> // or multipart/form-data
>>>>>
>>>>> // GET the state of an application 1
>>>>> GET http://localhost:8080/__asadmin/applications/1
>>>>>
>>>>> // Undeploy the application
>>>>> DELETE http://localhost:8080/__asadmin/applications/1
>>>>>
>>>>> // Redeploy the application
>>>>> PUT http://localhost:8080/__asadmin/applications/1
>>>>> // use application/x-www-form-urlencoded
>>>>> // or multipart/form-data
>>>>>
>>>>> // get the list of modules
>>>>> // returns a list of URIs for each module
>>>>> GET http://localhost:8080/__asadmin/modules
>>>>>
>>>>> // get the list of containers
>>>>> // returns a list of URIs for each containers
>>>>> GET http://localhost:8080/__asadmin/containers
>>>>>
>>>>> // get the version
>>>>> GET http://localhost:8080/__asadmin/version
>>>>>
>>>>> // get the domain state
>>>>> GET http://localhost:8080/__asadmin/domain
>>>>>
>>>>> // get the domain state
>>>>> PUT http://localhost:8080/__asadmin/domain
>>>>> // use application/x-www-form-urlencoded
>>>>>
>>>>> // get the high-level state of everything
>>>>> GET http://localhost:8080/__asadmin
>>>>>
>>>>>
>>>>> If using PUT/DELETE are in issue it is possible to wrap them in
>>>>> POST use a filter on the server side to set the appropriate HTTP
>>>>> method.
>>>>>
>>>>> Paul.
>>>>>
>>>>> [1] http://www.mnot.net/webdesc/
>>>>>
>>>>>> ~Jakub
>>>>>>
>>>>>>> which lists the commands, but I'm really looking for the one
>>>>>>> where if the "User-agent" is set to "hk2-agent", then specially
>>>>>>> formatted data is returned (e.g. Manifest format for
>>>>>>> list-applications, etc) and what the data can be expected to be.
>>>>>>>
>>>>>>> If no such document, when and where can I expect to find this
>>>>>>> information? Or do I have to read the source :o
>>>>>>>
>>>>>>> -Peter
>>>>>>>
>>>>>>> ---------------------------------------------------------------------
>>>>>>>
>>>>>>> To unsubscribe, e-mail: dev-unsubscribe_at_glassfish.dev.java.net
>>>>>>> For additional commands, e-mail: dev-help_at_glassfish.dev.java.net
>>>>>>>
>>>>>
>>>>> --
>>>>> | ? + ? = To question
>>>>> ----------------\
>>>>> Paul Sandoz
>>>>> x38109
>>>>> +33-4-76188109
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> To unsubscribe, e-mail: dev-unsubscribe_at_glassfish.dev.java.net
>>>>> For additional commands, e-mail: dev-help_at_glassfish.dev.java.net
>>>>>
>>>>
>>>> ---
>>>> Lloyd L Chambers
>>>> lloyd.chambers_at_sun.com
>>>> Sun Microsystems, Inc
>>>>
>>>>
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe_at_glassfish.dev.java.net
>>>> For additional commands, e-mail: dev-help_at_glassfish.dev.java.net
>>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe_at_glassfish.dev.java.net
>>> For additional commands, e-mail: dev-help_at_glassfish.dev.java.net
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe_at_glassfish.dev.java.net
>> For additional commands, e-mail: dev-help_at_glassfish.dev.java.net
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: dev-help_at_glassfish.dev.java.net
>