View source | Discuss this page | Page history | Printable version   
Toolbox
Main Page
Upload file
What links here
Recent changes
Help

PDF Books
Add page
Show collection (0 pages)
Collections help

Search

XML REST Web Services

Contents

Overview

Openbravo ERP REST consists of a framework offering security and exception services and a data access REST web service implementation. The data access (DAL) REST web services provide a CRUD-like web service so that external applications can retrieve, update, create and delete business objects through standard HTTP requests.

Glossary

This document uses the term business object to denote an entity and its dependent information. A business object can be a simple entity such as a currency which just has basic primitive fields. On the other hand it can also be a structure of entities, for example an order header with its order line. A business object structure always has one business object which is the owner of all the business objects in that structure, for example for a sales order the sales order header business object is the owner of the complete structure. Another way of describing this is that the order lines depend on the order header, i.e. an order line can not exist without its order header and when an order header is removed also the order line should be removed.

Some background information related to REST:

The REST concept was first described by Roy Fielding:

An overview article on REST with a lot of links to other material:

A quick intro into an example REST approach:

Some links related to REST versus SOAP, there is a fair amount of articles on the web on this topic:

Why REST?

There are a number of reasons why a REST approach makes sense for a data centric service: a REST approach

REST Webservice

It is important to note that REST is not a standard but more an approach or architectural style. Openbravo ERP REST adheres to the REST approach:

Main REST Webservice

A request is processed by the REST web service servlet (org.openbravo.service.web.BaseWebServiceServlet). This servlet uses the request URL to determine the type of request and how to handle it.

The REST web service servlet also handle login and authentication (see below).

A request (GET, POST, PUT) can consist of three parts:

A GET request will not have content and is completely controlled by the url path and its parameters.

A POST and PUT request will have content which is assumed to be a valid xml document.

The response of a REST call will be an XML document, containing the requested data, a result XML message or an error XML message.

DAL REST Web service

The DAL REST web service is an implementation of a REST web service in Openbravo ERP 2.50. It provides a CRUD-like web service so that external applications can retrieve, update, create and delete business objects through standard HTTP requests.

It provides the following functionality:

The rest of this document will mainly focus on the functionality of the DAL REST web services.

Single Request and Response

A single request is a request which points to one unique business object. For example the url:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country/106 (User Name: Openbravo / Password: openbravo)

will return the xml for an instance of the Country business object with ID = 106 (Spain). The REST Webservice will retrieve this business object from the database, create XML for it and return the resulting XML. See below for a description of the XML.

Query Request and Response

A query url is used to retrieve a list of business objects. It can handle filter, sort and paging parameters. An example of a query url: for example:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country?where=currency.id='100'&orderBy=name&firstResult=5&maxResult=10 

(User Name: Openbravo / Password: openbravo)

This url will return all Country objects which have ID = 100 (USD) as currency, sorted by the country name, the page starting at object 5 and 10 objects should be returned.

To query on date fields for a specific date it is easiest to use a larger/smaller than, this because date fields are stored in the database with a time value (which can include milliseconds):

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country?where=currency.updated%3E'2012-11-20'%20and%20currency.updated%3C'2012-11-21'&orderBy=name&firstResult=5&maxResult=10

(note the %3E is an encoded > and the %3C is an encoded >)

The REST query functionality supports the following parameters in the url:

The user has two types of possible operations which can be performed by the query:

The default query operation will return the business objects (with their child objects) as XML. See the business-object-to-xml section. If you only want to have the objects returned without children then you can pass the includeChildren parameter (as a URL parameter) with the value false.

Note: when doing querying with the whereclause any special characters should be url encoded, for example the % character when doing like has to be encoded with %25, like this:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country?where=name like '%25Fr%25' (User Name: Openbravo / Password: openbravo)

Note: Notice that in this first example:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country?where=currency.id='100'&orderBy=name&firstResult=5&maxResult=10

is it also possible to query the server using the currency identifier returned. Nevertheless, for this case we must use the original name of the identifier, in the currency table it is ISO_CODE so the query would change to:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country?where=currency.iSOCode='USD'&orderBy=name&firstResult=5&maxResult=10

Note Notice that the where clause can also be used with more than one condition using the AND clause, e.g.

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country?where=currency.id='100'%20and%20hasRegions=true

Retrieval of a subset of the entity properties

Bulbgraph.png   This functionality is available in 3.0MP27 and later MPs.

Using the parameter _selectedProperties it is possible to specify the list of properties that the webservice should return. This parameter can be used both in single and query requests.

For instance, to retrieve only the id and name of all countries:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country?_selectedProperties=id,name

The list of properties can include not only properties of the top level entity, but also of its child entities. For instance this URL retrieves the id and name of each country, and the id and identifier of each of its regions:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country?_selectedProperties=id,name,regionList

Properties of the child entities can also be specified. For instance, to additionally obtain the name and description of each of the country regions:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country?_selectedProperties=id,name,regionList,regionList.name,regionList.description

The use of the _selectedProperties parameter has a benefitial effect on the performance: the fewer child entities are specified, the better the performance of the webservice call will be.

Update/Create Request and Response

A business object can be updated/created through REST using the http POST or PUT command. The posted XML should adhere to the XML Schema generated by the REST Webservice. With one exception, for update situations it is allowed to only include the changed properties in the XML.

The system will automatically check (by querying) if a business object is new or not. If no id is supplied then it will always be considered as new, if a id is supplied then a database query is done. If the id exists (for that type) in the database then the system will assume an update. If the id does not exist it is an insert, in which case the id (in the xml) is maintained.

If the update was successful a success response is returned (<success/>), if it fails an error XML response is send back.

Remove Request and Response

The DAL REST webservice also supports a delete or remove request. Delete requests use the http DELETE command. The Delete action can accept two types or urls:

http://localhost:8080/openbravo/ws/dal/Product/1000004

http://localhost:8080/openbravo/ws/dal/Product?where=name='C02'

In the second case it is possible to remove multiple objects in one http DELETE request.

Update multiple business objects Request and Response (Import)

The system also supports updating of multiple business objects which are passed in one file. The following aspects need to be taken into account:

A XML file containing different types can be posted to the generic DAL web service url:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal (User Name: Openbravo / Password: openbravo)

Business Object to XML

The XML response to a retrieval request consists of the data of the business object or business objects. The business object is translated to xml in the following way:

Property values are xml-ised as follows:

The element used for the XML version of a reference is also used in case when lists of references need to be exported.

DAL REST: Overview of return messages in XML

The design discusses different functionalities. To summarize this section lists the set of return types which can be expected for different types of REST requests:

If the requests fails then an error XML message is returned.

HTTP Return Codes

The REST Webservice uses the following error codes:

Login and Security

The REST Webservice provides two methods for logging in:

The following aspects are of importance for security:

Also, the default role for the user who is doing the log in should be enabled to do calls to web services. Search for "Is Web Service Enabled" inside the Role document for more information.

After a successfull login the REST web service action is run within the context of the user. The REST webservice uses the DAL security control mechanism to control read and write access.

Database Transaction

A REST web service request is basically the same as a normal HTTP request. This means that transaction handling is the same as for standard HTTP requests. If no exception occured then the transaction is committed at the end of the web service request (on the Openbravo server).

Non-updatable fields: Client, Organisation etc.

There are a number of properties for each business object which are not always changeable through the REST webservice:

XSD Schema Generation for REST approach

The DAL webservice generates a XSD schema on the basis of the runtime model. This XSD schema defines the xml which is generated by the REST web service. This definition is also used for the XML used to update Openbravo through REST web services.

For an Openbravo ERP instance running on http://livebuilds.openbravo.com/erp_pi_pgsql the XSD can be retrieved through this request:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/schema (User Name: Openbravo / Password: openbravo)

Error Handling

When a request can not be processed and an error occurs then an error XML document and the relevant HTTP response code is returned. The error XML document contains the exception message.

The stacktrace and other more detailed information is not sent out on purpose (because of security reasons).

Simple XSLT templates

Openbravo ERP 2.50 has some simple XSLT templates to show how the XML can be processed and demonstrate that REST is a good approach for allowing navigation through data sets. The following URL shows the start URL for a DAL web service call using the XSLT templates:

http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/?template=types.xslt (User Name: Openbravo / Password: openbravo)
http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Country/106?template=bo.xslt (User Name: Openbravo / Password: openbravo)
http://livebuilds.openbravo.com/erp_pi_pgsql/ws/dal/Currency/100?template=bo.xslt (User Name: Openbravo / Password: openbravo)

The XSLT templates can be found in the org.openbravo.service.rest package.

Test

The REST Webservice functionality is tested using junit testcases. REST test cases can be found in the openbravo development project in the src-test folder and then in the org.openbravo.test.webservice package. The REST test cases give a first impression on how to do REST requests directly from Java incl. basic authentication.

Tips & tricks and trouble shooting

For trouble shooting and tips and tricks please see this link here. The tips and tricks section for example discuss a firefox plugin to make it easy to test REST webservices.

Retrieved from "http://wiki.openbravo.com/wiki/XML_REST_Web_Services"

This page has been accessed 18,008 times. This page was last modified on 18 December 2013, at 22:26. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.