Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

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

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

Round pegs could be considered POSTs, so maybe it's POSTing round pegs 
in square holes...

-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"<ad...@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
>>>>>>>>>>>

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

Martin,

Thank you for the feedback! Another alternative that was mentioned 
earlier was Apache CXF. Apache CXF and
Enunciate have one thing in common - REST services are implemented in 
Java. Some people prefer to work in Java, others prefer configuring 
things in XML. I'm the latter.

Btw, I have created a Jira issue where the design is taking place. I 
encourage anyone who is interested to check it out. I believe the 
solution proposed there makes implementing REST services trivial, and no 
Java coding is needed.

https://issues.apache.org/jira/browse/OFBIZ-4274

-Adrian

On 5/11/2011 7:40 AM, Martin Kreidenweis wrote:
> Hi,
>
> On 10.05.2011 13:07, Adrian Crum wrote:
>> 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.
> Why reinvent the wheel? We integrated Enunciate in OFBiz for our REST API. It adheres to the REST
> principles, is actually quite comfortable to use and was not hard to integrate into OFBiz.
> And it generates a nice documentation for the API from your JavaDoc. :)
> Have a look at it here: http://enunciate.codehaus.org/getting_started.html
>
> I'll paste some code snippets to get you started. Just ask if you need more details.
>
> Enunciate brings its own web app, which is actually generated.
> So we put it in hot-deploy/api/build/web-app. We just added the webapp to ofbiz-component.xml:
> <webapp name="api" location="build/webapp/basic-app" mount-point="/api" app-bar-display="false" ...
>
>
> Then you have to integrate enunciate in the build process, the component's build.xml should contain
> something like that:
>
>      <!-- we put the enunciate libraries here: -->
>      <property name="enunciate.home" value="enunciate/enunciate-1.20" />
>      <property name="enunciate.config" value="config/enunciate.xml" />
>      <property name="build.main.dir" value="build/classes/basic-app" />
>      <property name="build.tmp.dir" value="build/tmp" />
>
>      <!-- override classes target to call enunciate -->
>      <target name="classes" description="enunciate specific build step" depends="prepare">
>          <taskdef name="enunciate" classname="org.codehaus.enunciate.main.EnunciateTask">
>              <classpath refid="enunciate.classpath" />
>          </taskdef>
>
>          <delete dir="${build.tmp.dir}" />
>          <mkdir dir="${build.tmp.dir}" />
>
>          <enunciate basedir="src/main" configFile="${enunciate.config}" verbose="true"
> scratchDir="${build.tmp.dir}" generateDir="build/gen-src" compileDir="build/classes"
> buildDir="build/webapp">
>              <include name="**/*.java" />
>              <classpath refid="enunciate.classpath" />
>          </enunciate>
>
>          <javac16/>
>      </target>
>
>
> In the enunciate config file we configured enunciate not to do the actual build itself, but let the
> OFBiz build system do this:
>    <webapp doPackage="false" doLibCopy="false" doCompile="false" mergeWebXML="merge-web.xml">
>
>
> We also have a servlet filter for authorization configured.
>
> And our Enunciate Services all inherit from a BaseService class which provides the OFBiz delegator
> and dispatcher:
>      protected Delegator delegator = DelegatorFactory.getDelegator("default");
>      protected LocalDispatcher dispatcher = GenericDispatcher.getLocalDispatcher("api", delegator);
>
>
> In the Enunciate methods we can then call OFBiz services with dispatcher.runSync() and access the
> OFBiz database using the usual Delegator.
> So our mapping from OFBiz services to the REST paradigm is done in Java code, no XML configuration
> necessary here :-)
>
> Regards
> Martin

Re: Discussion: REST support in OFBiz

[Martin Kreidenweis <ma...@tngtech.com>]

Hi,

On 10.05.2011 13:07, Adrian Crum wrote:
> 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.

Why reinvent the wheel? We integrated Enunciate in OFBiz for our REST API. It adheres to the REST
principles, is actually quite comfortable to use and was not hard to integrate into OFBiz.
And it generates a nice documentation for the API from your JavaDoc. :)
Have a look at it here: http://enunciate.codehaus.org/getting_started.html

I'll paste some code snippets to get you started. Just ask if you need more details.

Enunciate brings its own web app, which is actually generated.
So we put it in hot-deploy/api/build/web-app. We just added the webapp to ofbiz-component.xml:
<webapp name="api" location="build/webapp/basic-app" mount-point="/api" app-bar-display="false" ...


Then you have to integrate enunciate in the build process, the component's build.xml should contain
something like that:

    <!-- we put the enunciate libraries here: -->
    <property name="enunciate.home" value="enunciate/enunciate-1.20" />
    <property name="enunciate.config" value="config/enunciate.xml" />
    <property name="build.main.dir" value="build/classes/basic-app" />
    <property name="build.tmp.dir" value="build/tmp" />

    <!-- override classes target to call enunciate -->
    <target name="classes" description="enunciate specific build step" depends="prepare">
        <taskdef name="enunciate" classname="org.codehaus.enunciate.main.EnunciateTask">
            <classpath refid="enunciate.classpath" />
        </taskdef>

        <delete dir="${build.tmp.dir}" />
        <mkdir dir="${build.tmp.dir}" />

        <enunciate basedir="src/main" configFile="${enunciate.config}" verbose="true"
scratchDir="${build.tmp.dir}" generateDir="build/gen-src" compileDir="build/classes"
buildDir="build/webapp">
            <include name="**/*.java" />
            <classpath refid="enunciate.classpath" />
        </enunciate>

        <javac16/>
    </target>


In the enunciate config file we configured enunciate not to do the actual build itself, but let the
OFBiz build system do this:
  <webapp doPackage="false" doLibCopy="false" doCompile="false" mergeWebXML="merge-web.xml">


We also have a servlet filter for authorization configured.

And our Enunciate Services all inherit from a BaseService class which provides the OFBiz delegator
and dispatcher:
    protected Delegator delegator = DelegatorFactory.getDelegator("default");
    protected LocalDispatcher dispatcher = GenericDispatcher.getLocalDispatcher("api", delegator);


In the Enunciate methods we can then call OFBiz services with dispatcher.runSync() and access the
OFBiz database using the usual Delegator.
So our mapping from OFBiz services to the REST paradigm is done in Java code, no XML configuration
necessary here :-)

Regards
Martin

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

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" <ad...@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"<ad...@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
>>>>>>>>>>>>>>>>>
>
>

Re: Discussion: REST support in OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

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" <ad...@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"<ad...@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
>>>>>>>>>>>>>>>> 

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@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"<ad...@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
>>>>>>>>>>>>>>>

Re: Discussion: REST support in OFBiz

[Scott Gray <sc...@hotwaxmedia.com>]

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"<ad...@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
>>>>>>>>>>>>>> 

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

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"<ad...@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
>>>>>>>>>>>>>

Re: Discussion: REST support in OFBiz

[Scott Gray <sc...@hotwaxmedia.com>]

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"<ad...@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
>>>>>>>>>>>> 

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

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"<ad...@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
>>>>>>>>>>>

Re: Discussion: REST support in OFBiz

[David E Jones <de...@me.com>]

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"<ad...@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
>>>>>>>>>> 
>>>> 

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

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"<ad...@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
>>>>>>>>>
>>>

Re: Discussion: REST support in OFBiz

[David E Jones <de...@me.com>]

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" <ad...@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
>>>>>>>> 
>> 
>> 

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

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" <ad...@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
>>>>>>>
>
>

Re: Discussion: REST support in OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

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" <ad...@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
>>>>>>

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@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
>>>>>

Re: Discussion: REST support in OFBiz

[Jacques Le Roux <jl...@les7arts.com>]

From: "Jacopo Cappellato" <ja...@hotwaxmedia.com>
> 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).

You think at something like in the link David sent http://apidoc.adility.com/submission-api#TOC-Response ?

Jacques

> 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
>>>>>
>
> 

Re: Discussion: REST support in OFBiz

[Jacopo Cappellato <ja...@hotwaxmedia.com>]

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
>>>> 

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

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
>>>

Re: Discussion: REST support in OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

Not REST but SOAP related but I guess is worth to be noted 
https://issues.apache.org/jira/browse/OFBIZ-4245
This prevent CXF to work with OFBiz when using SOAP

Jacques

From: "Raj Saini" <ra...@gmail.com>
> There is also JAX-RS Java API (http://en.wikipedia.org/wiki/JAX-RS). I 
> believe integrating current implementation  such as Apache CXF similar 
> to the way Axis is integrated for SOAP based web services should be less 
> work than doing it all ourselves.
> 
> Thanks,
> 
> Raj
> 
> On Thursday 05 May 2011 06:54 AM, 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
>>>>
>>
>

Re: Discussion: REST support in OFBiz

[Raj Saini <ra...@gmail.com>]

Jacques,

I am working on a prototype and let you know my findings.

Thanks,

Raj

On Friday 06 May 2011 03:31 PM, Jacques Le Roux wrote:
> IIRW CXF uses Java annotations, is this not limiting us (simple-methods)?
> Raj did you think about an engine part of CXF to include in OFBiz?
>
> Jacques
>
> From: "Adrian Crum" <ad...@sandglass-software.com>
>> Raj,
>>
>> How do you picture Apache CXF being used in OFBiz? How would we map 
>> REST requests to OFBiz services using CXF?
>>
>> -Adrian
>>
>>
>> On 5/4/2011 9:48 PM, Raj Saini wrote:
>>> There is also JAX-RS Java API (http://en.wikipedia.org/wiki/JAX-RS). 
>>> I believe integrating current implementation  such as Apache CXF 
>>> similar to the way Axis is integrated for SOAP based web services 
>>> should be less work than doing it all ourselves.
>>>
>>> Thanks,
>>>
>>> Raj
>>>
>>> On Thursday 05 May 2011 06:54 AM, 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
>>>>>>
>>>>
>>>
>
>

Re: Discussion: REST support in OFBiz

[Jacques Le Roux <ja...@les7arts.com>]

IIRW CXF uses Java annotations, is this not limiting us (simple-methods)?
Raj did you think about an engine part of CXF to include in OFBiz?

Jacques

From: "Adrian Crum" <ad...@sandglass-software.com>
> Raj,
> 
> How do you picture Apache CXF being used in OFBiz? How would we map REST 
> requests to OFBiz services using CXF?
> 
> -Adrian
> 
> 
> On 5/4/2011 9:48 PM, Raj Saini wrote:
>> There is also JAX-RS Java API (http://en.wikipedia.org/wiki/JAX-RS). I 
>> believe integrating current implementation  such as Apache CXF similar 
>> to the way Axis is integrated for SOAP based web services should be 
>> less work than doing it all ourselves.
>>
>> Thanks,
>>
>> Raj
>>
>> On Thursday 05 May 2011 06:54 AM, 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
>>>>>
>>>
>>

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

Raj,

How do you picture Apache CXF being used in OFBiz? How would we map REST 
requests to OFBiz services using CXF?

-Adrian


On 5/4/2011 9:48 PM, Raj Saini wrote:
> There is also JAX-RS Java API (http://en.wikipedia.org/wiki/JAX-RS). I 
> believe integrating current implementation  such as Apache CXF similar 
> to the way Axis is integrated for SOAP based web services should be 
> less work than doing it all ourselves.
>
> Thanks,
>
> Raj
>
> On Thursday 05 May 2011 06:54 AM, 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
>>>>
>>
>

Re: Discussion: REST support in OFBiz

[Raj Saini <ra...@gmail.com>]

There is also JAX-RS Java API (http://en.wikipedia.org/wiki/JAX-RS). I 
believe integrating current implementation  such as Apache CXF similar 
to the way Axis is integrated for SOAP based web services should be less 
work than doing it all ourselves.

Thanks,

Raj

On Thursday 05 May 2011 06:54 AM, 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
>>>
>

Re: Discussion: REST support in OFBiz

[Adrian Crum <ad...@sandglass-software.com>]

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
>>

Re: Discussion: REST support in OFBiz

[Scott Gray <sc...@hotwaxmedia.com>]

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
>