View source | Discuss this page | Page history | Printable version   

ERP 2.50:Developers Guide/Concepts/REST Web Services/zh cn

Contents

概述

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

术语

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:

为什么用表述性状态转移(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 REST adheres to the REST approach:

主要表述性状态转移(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 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://www.openbravo.com/dal/AccountingAcct/5 will return the xml for an instance of the AccountingAcct business object with id 5. 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://localhost:8080/openbravo/ws/dal/FinancialMgmtAccountingFact?where=businessPartner.id='1000004'&orderBy=businessPartner.name,locationToAddress.region.name&firstResult=19&maxResult=10. This url will return all FinancialMgmtAccountingFact objects which have a business partner with id 10000004, sorted by the business partner name and region.name of the to-location, the page starting at object 19 and 10 objects should be returned.

The REST query functionality should support the following parameters in the url:

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

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://localhost:8080/openbravo/ws/dal/ADClient?where=name like '%25azaar%25'

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 (see below). 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 expects a single URI pointing to the business object which needs to be removed.

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://localhost:8080/openbravo/ws/dal

(assuming that Openbravo runs on localhost:8080/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-ished 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返回代码

The REST Webservice uses the following error codes:

登录和安全性

The REST Webservice provides two methods for logging in:

The following aspects are of importance for security:

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

数据库事务

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 instance running on localhost:8080/openbravo the XSD can be retrieved through this request:

http://localhost:8080/openbravo/ws/dal/schema

出错处理

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

简单XSLT模板

Openbravo 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://localhost:8080/openbravo/ws/dal/?template=types.xslt

(assuming that Openbravo runs on localhost:8080/openbravo)

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

测试

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.

技巧& tricks 和快速诊断

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/ERP_2.50:Developers_Guide/Concepts/REST_Web_Services/zh_cn"

This page has been accessed 2,654 times. This page was last modified on 14 June 2011, at 11:03. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.