[jira] Commented: (CONNECTORS-98) API should be pure RESTful with the API verb represented using the HTTP GET/PUT/POST/DELETE methods
[
https://issues.apache.org/jira/browse/CONNECTORS-98?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=12908557#action_12908557
]
Karl Wright commented on CONNECTORS-98:
---
bq. http://www.infoq.com/articles/rest-introduction
This article's use of PUT vs. POST is rather different than the HTTP
specification and every other REST article's usage that I've seen so far. I
think that should remind you that there is indeed no real standard, so you run
a real chance of chasing a wil-o-the-wisp if you take everyone's individual
convention as gospel.
I think this applies to use of plural. Your articles differ on this, as do
most of the articles I read too. Really the important thing is whether you can
write a URL for every object. Nothing else is as crucial.
So I think *we* are going to have to agree on our own conventions for this API,
which may or may not agree 100% with other peoples'. Here are some proposals.
(1) We will continue to use the connection_name as the key for connection
collections, because it is, but we encode it in some way, because we have to.
Please acknowledge that this is acceptable.
(2) HTTP states that PUT should generate a 201 return when the resource is
being created. That implies that you should use PUT to create a resource.
That's fine for resources that include their own primary key, such as
connections, but does not work for jobs, which mint a unique ID when they are
created. For those kinds of entities, I believe the right thing to do is use a
POST on the parent, e.g. POST /jobs, but some reference materials are pretty
loose about this kind of thing. But then the issue is, how exactly is the new
job's ID supposed to be returned to the caller? Because that obviously must
happen.
One way is to provide a GET command that just returns a unique ID, and separate
out the id minting from the job saving. That seems cumbersome, but will be
necessary if there's no other way. Or, is POST allowed to return a json
response containing the ID? None of the references so far demonstrates a
comparable model - or maybe I missed it. Can you confirm what should be done
here.
(3) Use of plural/singular. I don't really care much. Pick something and let
me know and we'll stick with it.
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.
[jira] Commented: (CONNECTORS-98) API should be pure RESTful with the API verb represented using the HTTP GET/PUT/POST/DELETE methods
[
https://issues.apache.org/jira/browse/CONNECTORS-98?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=12908561#action_12908561
]
Mark Miller commented on CONNECTORS-98:
---
I agree - I think the best REST is sticking by most of the general practices as
you can / makes sense - but more importantly, just be consistent. While it can
be nice to stick to the http spec / REST gospel when you can, sometimes it just
makes sense to be a little different.
bq. (2) HTTP states that PUT should generate a 201 return when the resource is
being created.
Both PUT and POST can be used to create according to HTTP.
bq. (3) Use of plural/singular. I don't really care much. Pick something and
let me know and we'll stick with it.
I agree - it's only important to be consistant internally here - otherwise, who
cares.
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.
[jira] Commented: (CONNECTORS-98) API should be pure RESTful with the API verb represented using the HTTP GET/PUT/POST/DELETE methods
[
https://issues.apache.org/jira/browse/CONNECTORS-98?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=12908575#action_12908575
]
Karl Wright commented on CONNECTORS-98:
---
bq. The first upshot of this is that the client needs to encode spaces as +
or %20. Ditto for other reserved chars (described in an earlier comment.)
Yes, in fact as we discussed before, the entire name must be URL-encoded using
a method like java.net.URLEncoder.encode(). However, that's not enough,
because of the / problem, so I proposed that BEFORE the client does the URL
encoding, it does slash-encoding as well.
bq. A second upshot of this is that we can't use .+ in the original path from
the client to encode slash since it would come through to the ACF server app as
.space. So, either the client would have to write .%2B or we pick some
other encoding. Lacking some more preferred choice, we could simply propose
.- as our encoding for slash. Almost any (non-reserved) char will do.
Actually, since the URL encoding takes place afterwards, you can use any
character you want. So, if you tried my original proposal with your example,
you would actually get:
GET
info/outputconnections/this+updated.%2crevised+example+connection+1..0/command
(I think %2c is %-encoded +, right? Too lazy to look it up...)
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.
[jira] Commented: (CONNECTORS-98) API should be pure RESTful with the API verb represented using the HTTP GET/PUT/POST/DELETE methods
[
https://issues.apache.org/jira/browse/CONNECTORS-98?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=12908581#action_12908581
]
Jack Krupansky commented on CONNECTORS-98:
--
Just to confirm, as requested, that I am comfortable sticking with connection
name (and job name, etc.) in API paths as opposed to using a more abstract id
since we seem to have an encoding convention to deal with slash so that an ACF
object name can always be represented using a single HTTP path segment. Names
clearly feel more natural and will be easier to use, both for app code using
the ACF API and for CURL and other scripting tools.
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.
