XML-RPC Interface ("SOA")
Purpose of the Interface
The purpose of this interface is to allow external applications
to access the main data structures of ]project-open[
and its underlying OpenACS infrastructure.
The design priority was easy access beyond
any other feature.
Contents
Overview
 |
- Communication Need:
An application needs to read or modify ]po[
objects. All ]po[
objects can be found in the database, so the application
needs somehow access to the data model.
- ODBC is Blocked:
ODBC access is frequently blocked by a Firewall or is unavailable
for other reasons.
- XML-RPC Communication:
Instead, the client application can access the ]po[
data model via HTTP and HTTPS.
|
| Client - server communication via HTTP,
HTTPS or ODBC. |
General Interface Structure
This interface implements a generic XML-RPC bridge to the ]po[
(SQL) data model. The interface basicly lets you execute a selected
number of SQL statements. This type of interface is possible because
the all ]po[
objects are stored in the database in an object-oriented fashion
with metada. Caching in the memory only applies to slowly changing
master data which are out of the scope of this interface.
Communication Example
The following example shows a sample communication between a client
and a server, querying and updating information about a employee.
 |
- Login:
The client authenticates using email/pwd combination. "Timestamp"
specifies the requested validity period.
- Select:
The client requests a list of all ("{}" indicates
an empty list of constraints) objects of type "im_employee"
and receives a list of object_id's
- Object_Info:
The client requests all available information about the
object with the ID 601.
- Update:
The client updates the first_name of the object #601.
|
| Client - server communication protocol
example. |
XML-RPC
The interface uses the "XML-RPC" standard for transport-level
encoding. XML-RPC defines how business information can be communicated
from one computer to another as XML documents via HTTP(S).
XML-RPC is the "little brother" of SOAP, with a greatly
reduced complexity, but also with certain restrictions. Writing
the prototype of an XML-RPC interface to ]po[
only takes minutes for developers familiar with XML. XML-RPC libraries
exists for all major development environments, including MS-VisualBasic
(for Applications), C#, C/C++, Perl, Python, Ruby, ...
XML-RPC defines how data is packages and sent between applications.
However, it doesn't define what is being transmitted and how errors
are handeled.
Object Model
A ]po[
object consists of an object_id, an object_type and a number of
fields that can be stored in more then one table. In particular,
derived object types (such as "im_employee", for example)
consist of information that are stored in more then one table.
The SQLAPI provides a consistent layer that hides the fact that
information may be stored in different tables. For SQLAPI, an object
consists of a set of attributes.
Application-Level Protocol Overview
The ]po[
XML-RPC currently defines the "SQLAPI" protocol that implements
a generic SQL Bridge in order to reduce the number of procedures.
It defines the following set of remote procedure calls (RPCs):
- SQLAPI.Login:
Authenticate the client and generate a session key.
- SQLAPI.Object_Types:
Returns the list of all object types in the system.
- SQLAPI.Select:
Allows to retreive a set of objects of a specific object_type,
based on a number of selection criteria. SQLAPI.SELECT somehow
resembles the SQL "select" command.
However, SELECT only returns a set of object_id's and does not
posess the advanced SQL functions such as joins, "order by",
"group by" etc.
- SQLAPI.Object_Fields:
Returns a list of all object fields, together with their SQL type.
- SQLAPI.Get_Object:
Returns all fields of a single object as a key-value list. OBJECT_INFO
takes into account fields from several tables ("extension
tables") as defined in the "DynField" ]po[
SQL metadata system. For example, an "employee" object
is described by the tables "acs_objects" (basic object
information such as creation date, ...), "person" (first
and last name), "parties" (email, URL), "users"
(login and authentication information) and "im_employees"
(recruiting and payroll information).
- SQLAPI.PlPgSQL:
Execute any PlPg/SQL procedure. These procedures are used to create
new objects and to delete objects. Please see the data model reference
for available PlPg/SQL routines and their arguments.
- SQLAPI.Update:
Allows to modify an existing objects. UPDATE works similar to
"OBJECT_INFO" by updating information in all "extension
tables" of an object.
Execution Status and Error Treatment
All SQLAPI methods return a list of values with the first element
being the error status. The string "ok" indicates a successful
execution. Any other value indicates an error situation, with the
second element being a human readable error message.
Stateless Protocol Authentication
"SQLAPI" is a "stateless" protocol. That means
that each remote procedure call is executed independently from any
previous procedure call.
This means that the client has to maintain the session state and
needs to send authentication information with every procedure call.
This "auth_info" structure consists of a list that is
returned by the SQLAPI.Login call. It has the following structure
("[" and "]" indicating the start and end an
ordered list):
["token", user_id, timestamp, token]
- The literal "token" as the first element indicates
that token-based authentication is used. Other types of autentication
may be supported in future versions.
- "user_id" indicates the ID of a ]po[
user as defined by the "parties" table in ]po[.
- "timestamp" is a SQL timestamp in the format "YYYY-MM-DD
HH:MM:SS" (for example: "2006-08-05 14:48:09" to
indicate the 5th of August, 2006 at 2:48pm of the server's default
timezone). You can use the empty string to indicate an infinite
end date.
- "token" is a base64 encoded alphanumeric string of
40 characters returned by the server. The token represents a cryptographic
SHA1 hash signature of users's password. The exact length of the
token may vary in the future and occupy up to 1024 characters.
|
