 |
|
Service guidelines
Description
Service
Safe service
A service represents a specialized business function. A service is safe if it does not incur any obligations from its invoking client, even if this service may cause a change of state on the server side. A service is obligated if the client is held responsible for the change of states on server side. Safe Service
A safe service should be invoked by the GET method of HTTP. Parameters needed to invoke the service can be embedded in the query string of a URI. The main purpose of a safe service is to obtain a representation of a resource. Service Provider Responsibility [BP]
If there is more than one representation available for a resource, the service should negotiate with the client as discussed above. When returning a representation, a service provider should set the HTTP headers that relate to caching policies for better performance.
A safe service is by its nature idempotent. A service provider should not break this constraint. Clients should expect to receive consistent representations.
We next discuss each type of safe services in details.
Simple service
Request: GET {service uri}
Response: {A XML response specific to the service}
If there is any industry standards available, the response should conform to available standards as much as possible.
Query service
A query service returns a list of child resources. Usually, the representation of a resource is not returned, instead, only the meta view is returned.
Request: GET {service uri}
Parameters
| Parameter name | Description | Example |
| start | The start of the result set | |
| limit | Maximum number of resources to be returned | |
| iterator | If set to true, an iterator should be created | true|false |
| sortBy | Sort the result set by the metadata specified by this parameter | |
| reverse | If set to true, reverse the sorting order |
Response:
<result total="{total number of resources found.}" start="{the start number of the resource}" limit="{total number of results returned}" xmlns="" >
{A XML response specific to the service}
<iterator>
<prev start="{the start of number of the result set}" limit="{total number of resources returned}" />
<next start="{the start of number of the result set}" limit="{total number of resources returned}" />
</iterator>
</result>
Obligated Services [ BP ]
Obligated services should be implemented using POST. A request to an obligated service should be described by some kind of XML instance, which should be constrained by a schema. The schema should be written in W3C XML Schema or Relax NG. An obligated service should be made idempotent so that if a client is unsure about the state of its request, it can send it again. This allows low-cost error recovery. An obligated service usually has the simple semantic of "process this" and has two potential impacts: either the creation of new resources or the creation of a new representation of a resource.
Synchronous Services
A synchronous service returns business results immediately after receiving request. If a service takes long time to process a request, it should be implemented as an asynchronous service.
Request: POST {service uri}
Parameters
| Parameter name | Description | Example |
| lang | The language of response |
Request body: {service specific XML instance}
Success response:
<result status="success" xmlns="http://www.xmlpipe.org/xpe/manual" >
<l:msg lang="{zh-gb|en|...}" xmlns:l="http://www.xmlpipe.org/log" >
Any messages, the service might want to respond
</l:msg>
?
</result>
Error response:
<result status="error" code="{error code}" xmlns="http://www.xmlpipe.org/xpe/manual" >
<l:msg lang="{zh-gb|en|...}" xmlns:l="http://www.xmlpipe.org/log" >
Error messages
</l:msg>
<l:debug xmlns:l="http://www.xmlpipe.org/log" >
Debug information
</l:debug>
</result>
Note:
- All elements under the namespace,http://www.xmlpipe.org/log, are optional;
- If lang is set, the msg element should return a message in the language specified by the language code;
- Service specific extensions can be added to the result element. Consumers do not understand the extensions should just ignore the them.