Common System Specific Elements
- Sanjay Dalal (Unlicensed)
- Aron Roberts (Unlicensed)
work in progress
Each CollectionSpace Service receives an HTTP request and responds with an HTTP response. These requests and responses share a common set of data that is exchanged between the service consumer and provider. Let's call it system specific data. This page describes elements of the system specific data.
The system specific data could be found in one or more of the following places in a request, a response or both.
The requirement of the data is further categorized according to the type of operation (GET (R ead), PUT (U pdate), POST (C reate), DELETE (D elete)).
The information is categorized in the following general categories.
Common
Common elements should be present in request or response of any service-specific operation performed on the service layer.
Security
Security elements should be present in any service invocation performed in a secure manner.
Error
Error related elements are present in responses from the services layer where a system or service specific error occurs. If the operation is successful, no error related elements should be expected to be present in the responses.
XML Schema
<!-- error related information -->
<!-- available only if error/exception occurs on the service side -->
<xs:element name="error" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<!-- error code is mandatory in case of error -->
<xs:element name="code" type="xs:string" minOccurs="1" maxOccurs="1"/>
<!-- error message -->
<xs:element name="message" type="xs:string" minOccurs="0" maxOccurs="1"/>
<!-- id of resource if available -->
<xs:element name="resource-id" type="xs:string" minOccurs="0" maxOccurs="1"/>
<!-- uri of request -->
<xs:element name="request-uri" type="xs:anyURI" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Tenancy
Tenancy specific elements in responses provide additional information about the tenant under whose privileges the service invocation is carried out. The service layer automatically retrieves the tenant related information of the service consumer at the time of login and associates the information with the rest of the authentication context.
XML schema
<!-- tenant related information -->
<!-- available only in multi-tenant mode -->
<xs:element name="tenant-context" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<!-- tenant id would usually be in the form of UUID -->
<!-- tenant id might also identify Nuxeo repository id -->
<!-- system generated -->
<xs:element name="id" type="xs:string" minOccurs="1" maxOccurs="1"/>
<!-- tenant name could be domain name, e.g.sfmoma.org -->
<xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:element>
Query and Resultset
(TBD)
Asynchronous Service
For those services executing one or more long lasting activity and managing one or more state, there would be a need to get the status of the activity as well as to administer and to monitor the activity once it is started. The status of the activity could be retrieved at some later time (after the activity starts) using the information returned in response to the request that starts the activity.
XML Schema
<!-- async service related information -->
<!-- ref: XML.com REST Web Services Best Practices and Guide -->
<xs:element name="receipt" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<!-- timestamp available only in case of async services -->
<xs:element name="timestamp" type="xs:dateTime" minOccurs="1" maxOccurs="1"/>
<!-- uri of the request -->
<xs:element name="request-uri" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element name="activity-status" minOccurs="1" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="activity-uri" type="xs:string" minOccurs="1" maxOccurs="1"/>
<!-- status of the activity -->
<!-- it would be nice to share status between the activity-status and status service !-->
<!-- defined elsewhere -->
<xs:element name="status" minOccurs="1" maxOccurs="1">
<xs:simpleType>
<xs:restriction base="xs:string">
<!-- activity has started -->
<xs:enumeration value="started" />
<!-- request is accepted, validated and persisted -->
<xs:enumeration value="accepted" />
<!-- activity is completed successfully -->
<xs:enumeration value="completed" />
<!-- activity failed to completed -->
<xs:enumeration value="failed" />
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
XML response entity body schema
<?xml version="1.0" encoding="UTF-8"?>
<!--
Document : system-response.xsd
Created on : May 26, 2009, 1:31 PM
Author :
Copyright 2009 University of California, Berkeley
Description:
Schema for system specific information for service response envelope.
This envelope contains various contextual information such as error,
tenant and query. This context is over and above what is exchanged in
transport protocol specific session. e.g. cookies, headers and parameters
of HTTP session
-->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://collectionspace.org/services/common/system"
xmlns:tns="http://collectionspace.org/services/common/system"
elementFormDefault="qualified">
<xs:element name="system-response">
<xs:complexType>
<xs:sequence>
<!-- error related information -->
<!-- available only if error/exception occurs on the service side -->
<xs:element name="error" minOccurs="0" maxOccurs="1">
...
</xs:element>
<!-- tenant related information -->
<!-- available only in multi-tenant mode -->
<xs:element name="tenant-context" minOccurs="0" maxOccurs="1">
...
</xs:element>
<!-- async service related information -->
<!-- ref: XML.com REST Web Services Best Practices and Guide -->
<xs:element name="receipt" minOccurs="0" maxOccurs="1">
...
</xs:element>
<!-- query specific context -->
<!-- query context is available only for queries resulting in large result sets -->
<xs:element name="query-result" minOccurs="0" maxOccurs="1">
...
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>