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

Contents 1 概述 2 术语 3 为什么用表述性状态转移（REST）? 4 表述性状态转移 网络服务（REST Webservice） 5 主要表述性状态转移（REST）网络服务 Webservice 6 DAL REST Web service 7 Single Request and Response 8 Query Request and Response 9 Update/Create Request and Response 10 Remove Request and Response 11 Update multiple business objects Request and Response (Import) 12 Business Object to XML 13 DAL REST: Overview of return messages in XML 14 HTTP返回代码 15 登录和安全性 16 数据库事务 17 Non-updatable fields: Client, Organisation etc. 18 XSD Schema Generation for REST approach 19 出错处理 20 简单XSLT模板 21 测试 22 技巧& tricks 和快速诊断

概述

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:

• Fieldings's Dissertation

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

• Wikipedia on REST

A quick intro into an example REST approach:

• How to Create a REST Protocol
• Building Web Services the REST Way

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

• REST versus SOAP - the REST story
• A RESTful approach to Web services

为什么用表述性状态转移（REST）?

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

• favors identifying and addressing resources which fits to the data-centric nature of the provided apis (a resource corresponds to a business object)
• has actions (POST, PUT, DELETE, GET) which correspond to standard CRUD actions
• allows linking to specific business objects or to sets of business objects. This is a very powerfull feature of a REST approach and it allows for easy navigation between business objects.
• is simple to develop and use, and very lightweight from an architectural point of view

表述性状态转移 网络服务（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:

• resources (business objects) are identified by specific links which are stable over time
• the GET action is side-effect free
• all http actions: POST, PUT, DELETE, GET are supported
• http response codes are used to specify results of actions

主要表述性状态转移（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:

• URL路径
• URL参数
• the content of the request

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:

• retrieve a single business object using a url which contains both the type as well as the id of the request business object
• retrieve a list of business objects using just the type, for example http://www.openbravo.com/dal/AccountingAcct
• querying, filtering, paging and sorting of lists of business objects
• updating of an existing business object or multiple business objects through xml and a http POST or PUT operation
• creation of new business objects through a POST/PUT operation which submits a xml structure
• export and import of data: xml files which contain a mix of different types of business objects and a mix of new and existing business objects
• retrieval of a list of id and identifier values, for example to fill a listbox in an external user interface
• delete operation using either a url pointing to a specific business object which needs to be removed or a XML document (in the content) which contains business objects (as full xml or as partial xml) which need to be removed.

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:

• where: a HQL whereclause
• orderBy: an orderBy definition
• firstResult and maxResult parameters for paging support

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

• default when after the entity name there is no additional segment in the URL: this operation will query for the business objects and return (in XML) the properties of each of the business objects (this depends on security settings also).
• count: this will return the number of business objects which are selectable according to the filter. This action is used for support of paged views.

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:

• the xml file can contain mixes of new and existing (to-be-updated) business objects
• there maybe references to new business objects in the same xml file, these references use a unique id which does not need to in the database. This means that the import logic will internally (within the xml file) resolve object references before persisting the total xml file.
• the xml file can contain mixes of different types of business objects

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:

• The entity name is used for the tag name of the business object element. The entity tag/element also has attributes for the id and the identifier.
• The property name is used for the element name of each property. It depends on the security settings of the user which properties or information is returned (see security section).

Property values are xml-ished as follows:

• Date value is exported according to the XML Schema datetime format
• String value is exported as is (encoding is required)
• Numeric value is exported using decimal point and no grouping
• Reference (to another business object) is converted to an xml tag which contains the id, the entity name and the identifier value. This makes it possible for consumers of the XML to easily create hyperlinks to retrieve the data of the reference business object. The identifier can be used to generate a display of the reference.

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:

• a request for a specific business object will return a XML document with this business object
• a request (a query) for a list of business objects will return a XML document with the data of those business objects
• a request (a query) for a list of identifiers will return a XML document with the only the id, entity name and the identifier of each business object
• a query with a count parameter will only return a simple xml message with a count number (<count>5</count>)
• an update/insert request will return a success XML message (<success/>) if it succeeded, the return message will contain the id of the inserted record.
• a query with a identifier parameter will return a list of identifier values (one for each business object)

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

HTTP返回代码

The REST Webservice uses the following error codes:

• 200 (OK): for successfull requests
• 400 (Bad Request): in case the uri could not be parsed or in case of invalid xml
• 401 (Unauthorized): is returned when a security exception occurs
• 404 (Not found): if the entityname does not exist or the if an individual business object is addressed, if the business object does not exist. Note that a 410 (Gone) response could also be applicable here but it is less know therefore the 404 is used.
• 409 (Conflict): is returned for a POST or PUT action, specifies that the data which was posted is out-of-date or invalid.
• 500 (Internal Server Error): if an unrecoverable application error occured.

登录和安全性

The REST Webservice provides two methods for logging in:

• login with login/password passed as request parameters (the parameters names are resp. l and p)
• basic http authentication

The following aspects are of importance for security:

• The login and context are stored in a session for performance reasons
• If the caller/client is session-less (does not support cookies) then it is also possible to include login information in every request. This is less preferred from a performance point of view.

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:

• Client and Organisation: a webservice update of a business object may not change the Client and Organisation information. In creation mode the client may not be set, the organisation may be specified, if not specified then it is set from the user information.
• Update and Created audit fields: the update and created audit fields are not updatable/changeable through the webservice api.

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.