After thinking about this for a while, I came to the conclusion that the
REST servlet should have its own request config file. REST request
elements will be kept in their own config file and that file will be
specified in web.xml.
I will create a Jira issue and summarize what we've discussed in it. I
hope to have time to work on this in the next few months.
Thanks everyone for the feedback.
-Adrian
On 5/7/2011 5:38 AM, Jacques Le Roux wrote:
If we have another kind of request-map (rest-request-map) and another
servlet associated to it could we not also have another RequestHandler
class: RestRequestHandler.
Then we could have both types of request-map in the same controller
(Adrian's concern) but also a clear separation between the 2 ways
(Scott's main concern)
Not sure about Scott's deprecation concern. I don't envision it as a
big issue but did not think much about it.
Jacques
From: "Adrian Crum" <adrian.c...@sandglass-software.com>
I respect that, but looking at it from a newcomer's perspective, I
would expect all request mappings to be in the same file. I will
think about it more. Thanks for the feedback!
-Adrian
On 5/6/2011 8:11 PM, Scott Gray wrote:
I guess maybe I'm a controller purist as well? The current
controller and RequestHandler class pair are built specifically to
handle a certain type of request and I'd be a little concerned about
increasing the complexity of how to use it. And again my same
concern about setting a precedent applies here as well I think.
Using a completely separate controller would possibly also ease the
burden of deprecation later on once the service engine was
improved/replaced and the need for such mappings removed or reduced.
Regards
Scott
On 7/05/2011, at 2:51 PM, Adrian Crum wrote:
Thanks Scott!
I agree with that. We could have a controller.xml element that the
current servlet ignores and the REST servlet scoops up. Until
something like Moqui is in the project, I think mapping a REST
request URL to a service will be a good place to start. That would
satisfy the immediate need, and it could be modified or built out
further in the future. What do you think?
-Adrian
On 5/6/2011 7:43 PM, Scott Gray wrote:
My first feeling in response to modifying the service definition
with REST related elements/attributes was that of a purist and I
guess I still feel that way, a line needs to be drawn somewhere or
next we'll have SOAP-specific bits along with anything else
someone wants to jam in there once the precedent is set.
I think the best long term solution would be to agree that a
service name alone doesn't perhaps serve as the best form of
identification/location and that something like what Jacopo (and I
think David a while back, perhaps this is what Moqui does) has
suggested would make services much easier to identify whether
using REST or not. With 7000+ services I'm constantly frustrated
trying to locate the one I need and get to grips with what it does.
But yeah the other option (or perhaps necessary addition) would be
to perhaps create a new controller definition that goes
specifically with a REST servlet and provides support for features
in REST that can't be defined generically within a service
definition.
Regards
Scott
On 7/05/2011, at 2:08 PM, Adrian Crum wrote:
One last thing about this...
The idea of adding a REST element to the service definition was
based on convenience, but some service engine "purists" might
believe that it doesn't belong there. An alternative would be to
put the element in a separate file that maps REST requests to
services, but then that file could become "out of sync" if the
services referred to in it are deleted. An example of where that
approach is taken already is in the controller.xml file - where
request events are mapped to services. Maybe the controller.xml
file should be the place where REST requests are configured. I'm
completely undecided about that - I'm not sure which way is best.
Any input from the community would be appreciated.
-Adrian
On 5/6/2011 2:14 PM, David E Jones wrote:
Yes, POST semantics are more flexible in some ways in that it
implies that the resource in the message is added (created)
under the location specified, and because of this it supports
sending multiple resources to be added there. In theory there
could already be something under the location with the same
name, causing an update or replacement, but that seems to be
ignored, making POST seem slightly more natural as a create
instead of an update.
PUT is for placing the data at the location and I believe does
not support multiple resources in the message, and would either
create if nothing was at the location or update if something was
there, and I suppose that's why people consider it more for
update instead of create.
Either way, it's messed up IMO... but that goes back to my bias
against RESTful services as it seems to be using a protocol for
something that it what was not intended or designed for, and it
turns into repeated efforts to put round pegs in square holes
(or do I have that backwards?).
-David
On May 6, 2011, at 1:52 PM, Adrian Crum wrote:
Thanks David!
I was thinking we would need a servlet for this - because some
of the REST semantics are in the HTTP headers as well as in the
HTTP method. From what I've read, the generally accepted
convention is that POST is a create operation, and PUT is an
update operation. But I agree with you that we need to have the
method meaning clearly documented.
-Adrian
On 5/6/2011 10:40 AM, David E Jones wrote:
One bit of documentation I like that shows clearly how the
RESTful services are defined and what the messages look like
is the Adility API docs, such as this one:
http://apidoc.adility.com/submission-api
The nice thing (and actually many RESTful API docs do this) is
that they list each "service" for that service they tell you
which HTTP method is used, and what the path to the resource
is. The point of this style of mapping is because the HTTP
methods (GET, PUT, POST, DELETE) don't really map naturally
to, well, to anything. They don't even map well to CrUD
operations because PUT and POST are really meant for
submitting resources and both could technically result in a
create or update, though they have different intended uses and
semantics that confuse the matter further.
So, it's generally necessary to define service "locations"
(and mappings to the actual service) not just as a URL, but
with a HTTP method and URL pair.
On a side note, to handle all HTTP methods we'll need to
either modify the ControlServlet, or (maybe preferable, and
what I've done on other projects) just use a totally separate
servlet that is meant for the RESTful API. In other words,
because RESTful stuff relies more on lower level HTTP stuff it
is quite different from the more generic approach the
ControlServlet uses.
-David
On May 6, 2011, at 9:39 AM, Adrian Crum wrote:
Here is the Amazon REST API - it could be a good source of
ideas for implementation:
http://docs.amazonwebservices.com/AmazonS3/latest/dev/index.html?RESTAPI.html
-Adrian
On 5/6/2011 7:33 AM, Jacques Le Roux wrote:
After having read the response hyperlinks article I tend to
agree with Adrian. HATEOAS seems to me a really important
feature of
REST
I have still to read completly the 1st article Adrian
mentionned though. I mean
http://www.infoq.com/articles/rest-introduction
And yes I also prefer response-hyperlink instead of
hateoas-attributes
Jacques
From: "Adrian Crum"<adrian.c...@sandglass-software.com>
I don't like the idea of adding attributes to the existing
service element because we still need a way to specify
response
hyperlinks (HATEOAS), plus I imagine other sub-elements and
additional attributes will be needed as we build it out more.
I prefer to keep the attribute names similar to the names
used in the specification - so they will make sense to
developers who
are familiar with REST. I came up with a better name for
the hateoas-attributes element: response-hyperlink.
-Adrian
On 5/6/2011 2:23 AM, Jacopo Cappellato wrote:
What about adding the "noun" and "verb" attributes to the
"service" element?
BTW in order to write a good application I suspect that a
lot of services should be refactored to better fit into a
REST based
application.
A good candidate for a prototype could be the Webtools'
"Entity Data Maintenance" application: we could rewrite it
to work with
RESTful URIs like
webtools/entities/
webtools/entities/orderheaders/
webtools/entities/orderheaders?orderTypeId=SALES_ORDER
webtools/entities/orderheaders/10010 (CRUD using
GET/POST/DELETE)
webtools/entityrelations/orderheader (this will return
URLs of related entities)
We could provide different representations for the
responses (and this could also serve to reimplement the
"XML data export"
part).
Kind regards,
Jacopo
On May 5, 2011, at 5:06 PM, Adrian Crum wrote:
I'm thinking we could have a new element for the service
definition:
<service name="createExample"
default-entity-name="Example" engine="entity-auto"
invoke="create" auth="true">
...
<rest-attributes resource="example" method="POST"/>
...
</service>
The presence of the rest-attributes element implies the
service can be exported via REST.
So, a new Example can be created by sending an HTTP POST
request to
https://mydomain.com/rest/example
"HATEOAS" can be implemented with child elements:
<service name="createExample"
default-entity-name="Example" engine="entity-auto"
invoke="create" auth="true">
...
<rest-attributes resource="example" method="POST">
<hateoas-attributes resource="exampleItem" .../>
...
</rest-attributes>
...
</service>
<service name="createExampleItem"
default-entity-name="ExampleItem" engine="entity-auto"
invoke="create" auth="true">
...
<rest-attributes resource="exampleItem" method="POST">
<hateoas-attributes resource="example" .../>
...
</rest-attributes>
...
</service>
The REST servlet will use the hateoas-attributes elements
to construct URLs for the REST response.
What do you think?
-Adrian
On 5/4/2011 6:24 PM, Adrian Crum wrote:
Thanks Scott!
I agree - the REST URLs (or URIs) should represent
resources and the HTTP commands should represent actions
taken on those
resources. I guess I was trying to take a shortcut by
having REST URLs point directly to OFBiz services.
So we need a way to map REST URLs to the appropriate
services. Maybe the service definitions could include a
REST resource
identifier. That should be easy to implement.
How could we implement something like the "Link things
together" section of this article:
http://www.infoq.com/articles/rest-introduction
(That question is for the community, not Scott
specifically).
-Adrian
On 5/4/2011 5:54 PM, Scott Gray wrote:
Hi Adrian
My limited understanding is that RESTful URLs should
point to a data resource rather than service logic
resources. The verbs
(HTTP request method) are used to indicate the type of
operation (CRUD) to be performed on the noun (data
object). So you'd
have something like a URL that points to say the
"person" resource and using that URL you can GET a
person(s), create or
update (POST) a person(s) and DELETE a person.
If what I say above is correct then what OFBiz lacks
primarily is the ability to map a verb and nouns
combination to a
specific service. I believe David has taken some steps
to resolving that in Moqui which we could achieve by
altering the way
we define services or alternatively as a stop-gap
measure we could introduce an additional mapping layer
which defines
resource end-points and maps the request type to the
appropriate service (perhaps not so easy for POST
operations that use a
create or update approach but possible by checking for
the presence of specific record identifying parameters
to indicate an
update).
What you've described below sounds more like a regular
HTTP web service approach that just makes a bit more
use of the request
headers than we do currently.
Regards
Scott
HotWax Media
http://www.hotwaxmedia.com
On 5/05/2011, at 12:11 PM, Adrian Crum wrote:
I'm working on a project that might require accessing
OFBiz services via REST. I know there have been
discussions about using
Axis, and Chris Snow was able to get a REST library to
work with OFBiz. Please correct me if I'm wrong, but
it seems to me
OFBiz already has most of what is needed to implement
REST, so there shouldn't be any need to use any
additional libraries.
From what I understand, REST services are simply HTTP
requests sent to a particular URL to invoke a
particular service. The
request response contains any requested data in a
format the REST client specified in the request. The
HTTP commands GET,
POST, PUT, and DELETE are used in the requests. The
meaning of the REST HTTP commands are server-specific.
So here is what I'm thinking: Let's say we want to
access OFBiz services via REST. We don't need to
support the PUT and
DELETE commands because the services themselves
determine what actions will be performed on the data.
So, let's say that a
GET command gets information about the service, and
the POST command invokes the service.
From my perspective, this could be implemented in two
different ways: a REST servlet or a REST view handler.
In either case,
the basic flow would be something like:
1. Get service name from request URL, look up service
model. If export is false, return 404.
2. If service model auth is true, get credentials from
HTTP header. If no credentials, return 401. If
credentials are found,
attempt to log in user. If login fails, return 401.
3. If command is GET, get Accept content type(s) from
HTTP header, use those to find a converter. Convert
service model info
to requested type and put it in the response.
4. If command is POST, get content type from HTTP
header, use that to find a converter. Convert POST
data to service
parameters and invoke the service. Get Accept content
type(s) from HTTP header, use those to find a
converter. Convert
service result to requested type and put it in the
response.
So, we could implement REST with existing artifacts -
no additional libraries are needed (except maybe for
data conversions).
What do you think? I'm not a REST expert, so comments
are welcome!
-Adrian
