[
https://issues.apache.org/jira/browse/CONNECTORS-98?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12907686#action_12907686
]
Karl Wright commented on CONNECTORS-98:
---------------------------------------
So Jack,
I've worked through a small subset of the current API, and would like to make
suggestions. Basically, I'm suggesting equivalents for the following:
outputconnection/list
outputconnection/get
outputconnection/save
outputconnection/delete
outputconnection/checkstatus
outputconnection/execute/<command>
First, it is worth noting that each of these commands has a potential error
response, and in some cases, a null response. For example:
outputconnection/get
can yield:
{"outputconnection":<output_connection_object>} OR { } OR
{"error":<error_text>}
Thus, the reason that I qualified the actual returned object with
"outputconnection" was to distinguish this case from the other cases, one of
which represents "object not found", and the other which represents an error.
So I don't think that we should muck with the response since the current design
seems both necessary and sufficient.
Second, in the brave new REST world, not all of these are going to be able to
have the same path. There are simply too many operations for that to covered
with the available REST verbs. So we will have to have some other way of
describing those operations.
Third, although the ".../execute/..." command sounds like it causes something
to happen, in reality it is in fact always an information retrieval operation.
Thus it should always use the "GET" verb.
So, this is what I think is a reasonable proposal:
outputconnection/get (connection_name) -> GET outputconnection (connection_name)
outputconnection/save (output_connection_object) -> PUT outputconnection
(output_connection_object)
outputconnection/delete (connection_name) -> DELETE outputconnection
(connection_name)
outputconnection/list () -> GET outputconnections ()
outputconnection/checkstatus (connection_name) -> GET outputconnection/status
(connection_name)
outputconnection/execute/<command> (connection_name, arguments) -> GET
outputconnection/request/<command> (connection_name, arguments)
Effectively, this means we preserve the input and output arguments completely
as-is, and simply change the verb and predicate to suit the REST style.
Comments?
> API should be "pure" RESTful with the API verb represented using the HTTP
> GET/PUT/POST/DELETE methods
> -----------------------------------------------------------------------------------------------------
>
> Key: CONNECTORS-98
> URL: https://issues.apache.org/jira/browse/CONNECTORS-98
> Project: Apache Connectors Framework
> Issue Type: Improvement
> Components: API
> Affects Versions: LCF Release 0.5
> Reporter: Jack Krupansky
> Fix For: LCF Release 0.5
>
>
> (This was originally a comment on CONNECTORS-56 dated 7/16/2010.)
> It has come to my attention that the API would be more "pure" RESTful if the
> API verb was represented using the HTTP GET/PUT/POST/DELETE methods and the
> input argument identifier represented in the context path.
> So, GET outputconnection/get \{"connection_name":_<connection_name>_\} would
> be GET outputconnections/<connection_name>
> and GET outputconnection/delete \{"connection_name":_<connection_name>_\}
> would be DELETE outputconnections/<connection_name>
> and GET outputconnection/list would be GET outputconnections
> and PUT outputconnection/save
> \{"outputconnection":_<output_connection_object>_\} would be PUT
> outputconnections/<connection_name>
> \{"outputconnection":_<output_connection_object>_\}
> What we have today is certainly workable, but just not as "pure" as some
> might desire. It would be better to take care of this before the initial
> release so that we never have to answer the question of why it wasn't done as
> a "proper" RESTful API.
> BTW, I did check to verify that an HttpServlet running under Jetty can
> process the DELETE and PUT methods (using the doDelete and doPut method
> overrides.)
> Also, POST should be usable as an alternative to PUT for API calls that have
> large volumes of data.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
