Child pages
  • REST Service Implementation

Access to add and change pages is restricted. See: https://cwiki.apache.org/confluence/display/OFBIZ/Wiki+access

Skip to end of metadata
Go to start of metadata

Overview

This page is just being used by the author to record his thoughts/progress towards a REST Service Implementation for Ofbiz. Note this document is a work in progress. I'm still learning about REST as well, so this document may be inaccurate.

Why?

TODO

How?

Base url: https://localhost/webtools/control/RESTService/

Use similar implementation to SOAP and the SoapEventHandler (i.e. implement a RestEventHandler)

The service definitions could be extended to contain extra metadata. This metadata could be used to generate the WADL:

CRUD - CREATE

    <service name="createPerson" engine="java" default-entity-name="Person"
            location="org.ofbiz.party.party.PartyServices" invoke="createPerson" 
            auth="false" export="true" 
            rest-resource-name="person"
            rest-http-method="PUT,POST"
            >
        <description>Create a Person</description>

        <auto-attributes mode="IN" include="pk" optional="true"/>
        <auto-attributes mode="OUT" include="pk" optional="false"/>
        <auto-attributes mode="IN" include="nonpk" optional="true"/>
        <attribute name="preferredCurrencyUomId" type="String" mode="IN" optional="true"/>
        <attribute name="description" type="String" mode="IN" optional="true"/>
        <attribute name="externalId" type="String" mode="IN" optional="true"/>
        <attribute name="statusId" type="String" mode="IN" optional="true"/>
    </service>

The above service would be accessed at the url:

https://localhost/webtools/control/RESTService/person - where person = rest-resource-name in the service definition.

Note that the service can be accessed by PUT and POST. This is to allow a kludge for clients such as Flex that don't understand PUT.

There could be a single parameter passed to the PUT, which would be the map-Map xml document (text/xml) which would be the same document as would be passed in to the equivalent SOAPService. Alternatively, the parameters could be passed in as text/plain parameters. Question: which would be better? ... text/xml map-Map may be easier to implement whereas text/plain may be simpler for the client.

Similar to the request parameter(s), the response could be the map-Map document, or it may be possible to map service errors back to http response codes. The map-Map text/xml response would be the simplest to implement. We could event implement both response types. If we implemented both, the response to the client would be dependent on whether an accept="text/xml" or accept="text/plain" was sent by the client with the initial request.

CRUD - READ

TODO

CRUD - UPDATE

TODO

CRUD - DELETE

TODO

  • No labels

3 Comments

  1. The design for REST should adhere to the principles laid out in R.T. Fielding's "Principled design of the modern Web architecture".

    It should follow established best practices:

    1. Use nouns but no verbs: currently the service names are same as api names, e.g. editProduct should be /product
    2. GET method and query parameters should not alter the state
    3. Make use of plural nouns: i.e. /products to return collections and /product to return single
    4. Use sub-resources for relations
    5. Use HTTP headers for serialization formats
    6. Use HATEOAS: Hypermedia as the Engine of Application State is a principle that hypertext links should be used to create a better navigation through the API.
    7. Provide filtering, sorting, field selection and paging for collections
    8. Version the api
    9. Handle Errors with HTTP status codes
    10. Allow overriding HTTP method

    Items in this list are copied from http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/

  2. The request-maps in webtools regarding REST services don't seem to exist anymore.

  3. For more info on OFBiz REST, see  OFBIZ-4274 - Getting issue details... STATUS