As some of you may know we are currently prototyping a new user interface library. As part of the development for the new user interface we have developed a JSON REST webservice module.
This module is a very good example on how you can extend the Openbravo webservice functionality using Openbravo modularity. It shows how easy it is to extend Openbravo not only when coding your functionality but also when configuring your services (extending web.xml and other configuration files).
JSON is a light-weight data-exchange format used extensively for client-service communication in web based applications. The JSON REST module is similar to the standard Openbravo XML REST webservice in that it makes Openbravo information available through a webservice supporting CRUD operations.
The module can be downloaded from the forge here or can be installed from the central repository. After installing the module and restarting Openbravo you can try out the webservice directly. For example enter the following url in the address-bar of the browser:
http://localhost:8080/openbravo/org.openbravo.service.json.jsonrest/Country/100
This call will retrieve the Country business object with id 100 as a JSON string. You can save the returned content and open it in a text editor. The JSON will look like this:
{"_identifier":"United States","entityName":"Country","$ref":"Country\/100","id":"100","client":{"_identifier":"System","entityName":"ADClient","$ref":"ADClient\/0","id":"0","active":true},"organization":{"_identifier":"*","entityName":"Organization","$ref":"Organization\/0","id":"0","active":true},"active":true,"creationDate":"2009-10-26T19:20:06","createdBy":{"_identifier":"System","entityName":"ADUser","$ref":"ADUser\/0","id":"0","active":true},"updated":"2009-10-26T19:20:06","updatedBy":{"_identifier":"System","entityName":"ADUser","$ref":"ADUser\/0","id":"0","active":true},"name":"United States","description":"United States of America","iSOCountryCode":"US","hasRegions":true,"regionName":"State","phoneNoFormat":"Y","addressPrintFormat":"@C@, @R@ @P@","additionalPostalCode":false,"default":true,"language":{"_identifier":"English (USA)","entityName":"ADLanguage","$ref":"ADLanguage\/192","id":"192","active":true},"currency":{"_identifier":"USD","entityName":"Currency","$ref":"Currency\/100","id":"100","active":true}}
Each of the properties of the Country object is present for example. client, id, iSOCountryCode etc. Openbravo JSON REST adds some special properties: _identifier and $ref which can be useful on the client. Each foreign key reference is also represented in a special way. for example the Country refers to the English (USA) language, the reference to that language is represented like this in the JSON string:
"language":{"_identifier":"English (USA)","entityName":"ADLanguage","$ref":"ADLanguage\/192","id":"192","active":true}
the 'language' is the property of the Country then within brackets the information of the language object itself is present. Adding this information in the returned JSON string has as advantage that it is not needed to do extra requests from client to server to display all the details of the Country object (including referenced objects).
The JSON REST service also supports query and paging parameters, some examples:
- http://localhost:8080/openbravo/org.openbravo.service.json.jsonrest/Country: this will return all countries
- http://localhost:8080/openbravo/org.openbravo.service.json.jsonrest/Country?_startRow=10&_endRow=50&_sortBy=name this will return 40 countries (rows 10 to 50) sorted by name
- http://localhost:8080/openbravo/org.openbravo.service.json.jsonrest/Country?name=United&_textMatchStyle=startsWith this url will return all countries which start with United (which are for example United Arab Emirates, United Kingdom and United States).
- http://localhost:8080/openbravo/org.openbravo.service.json.jsonrest/Country?_where=currency.iSOCode='USD' returns all countries which have a currency with the isocode USD. The _where parameter can contain a valid HQL where-clause. contain all the clauses supported by HQL.
See the JSON REST Developers Manual for more details on the querying capabilities and on the format of the returned information. The JSON REST module uses the same authentication and authorization functionality as the XML REST webservice functionality and the data-access-layer.
The JSON REST service also supports insert, update and removal of information. To insert a new Country you have to post a message like shown below to the Openbravo application and use the POST HTTP method. To try this directly in your browser you can make use of a Firefox plugin like poster.
{data: {"entityName":"Country","active":true,"name":"Test","description":"Test Country","iSOCountryCode":"ZZ","hasRegions":true,"regionName":"State","phoneNoFormat":"Y","addressPrintFormat":"@C@, @R@ @P@","additionalPostalCode":false,"language":{"id":"192"},"currency":{"id":"100"}}}
You see the result below. The system replies with a response JSON object which contains all the data of the inserted Country. The important one to take note of is the id.
We will be using the id in the next step to update the name of the Country to a better one (if you try this your self, the id will be for sure different!).
{data: {"entityName":"Country","id":"FF80818124923C2C0124923D39A80002","name":"My Great Test Country"}}
The response will return the complete JSON object with a status code (0 for success).
Then to clean up, let's delete the newly created country. Use this url (replacing the id part with your id) and do a DELETE HTTP method request:
http://localhost:8080/openbravo/org.openbravo.service.json.jsonrest/Country/FF80818124923C2C0124923D39A80002
A response with status 0 is returned with the deleted object as the data entry. This clean up action concludes this short tutorial. I hope you found it interesting.
As always we welcome feedback. We will be using this module as part of our new Openbravo user interface development and extend it further based on new requirements.