source: trunk/phpgwapi/doc/xmlrpc/gw_interface.txt @ 2

Revision 2, 6.7 KB checked in by niltonneto, 17 years ago (diff)

Removida todas as tags usadas pelo CVS ($Id, $Source).
Primeira versão no CVS externo.

  • Property svn:eol-style set to native
  • Property svn:executable set to *
Line 
1
2
3Proposal for a Common Groupware Interface Standard
4
5(C) 2001-2004 Miles Lott <milos@groupwhere.org>
6
7September 13, 2001 and December 29, 2003
8
9Table of Contents
10
111 Scope
122 The Services
13    2.1 Overview
14    2.2 Detail
15        2.2.1 Contacts
16        2.2.2 Schedule
17        2.2.3 Notes
18        2.2.4 Todo
19    2.3 Examples in XML-RPC
203 Conclusion
21    3.1 Contacts:
22    3.2 Schedule:
23    3.3 Notes:
24    3.4 Todo:
25
26
27
281 Scope
29
30As many different opensource and freesoftware groupware systems
31are being developed, the full realization of the dream of
32a connected world should be prefaced by an agreement to
33interoperate. There are limited ways in which cooperation
34with these and commercial groupware systems may be achecived,
35the majority if not all of which were derived via the establishment
36of open standards. These might include email (POP3/IMAP),
37contacts(LDAP,vcard), or scheduling(ical/vcal). It is felt
38that while these have proven themselves to be very useful,
39they are insufficient to satisfy the real needs of a typical
40business environment.
41
42This document hopes to provide a reasonable, if limited,
43recommendation for a set of standardized methods to be used
44for groupware services interaction. More specifically, it
45hopes to address the need for such a standard as well as
46to spur discussion about the common service names and methods
47themselves.
48
49Examples will be given for implementations in XML-RPC, since
50this standard is relatively fixed and open.
51
52This document does not provide recommendations for the underlying
53access control system which would allow or deny a particular
54action.
55
56Also not discussed here is login and authorization to be
57used for initial access to a service provider.
58
592 The Services
60
612.1 Overview
62
63There are a few common services types that will be needed
64for minimum useability of a groupware server or application.
65They are:
66
67* Contacts
68
69* Schedule
70
71* Notes
72
73* Todo
74
75These services are represented already in places such as
76existing groupware client-server applications and also in
77the PalmOS basic-4 buttons and applications. Different systems
78may have different names for these services internally,
79e.g. Contacts - addresses, addressbook, people, Schedule
80- calendar, agenda, meetings.
81
82Within each of these services are some common methods that
83would be called to store, retreive, or update data:
84
85* read_list
86
87* read
88
89* save
90
91* delete
92
932.2 Detail
94
952.2.1 Contacts
96
97The concept of contacts may encompass local addressbooks,
98LDAP, and lists stored in other media. The purpose of the
99contacts service is not to duplicate or attempt to replace
100these. In some respects, it might do just that. But its
101goal is more so to provide a common and shareable way for
102the other core services to create, edit, and read a common
103user and address list. All of the other services may use
104the contact service to obtain record owner information to
105be used in access control. They would also use them when
106it is required to share this data, as with a meeting where
107other local and non-local users will be invited to attend.
108
109Contacts may include the local installed user base, users
110on other cooperative servers, or email addresses used for
111limited cooperation with other groupware services that are
112not compliant with this service scheme or implementations
113thereof. It could also include individuals using web-based
114or local ISP email services. The scope of this document,
115however, is to define the service with regard to the common
116methods to be used for server-server and client-server communications:
117
118* read_list
119
120This method is used to list contacts, with or without limits,
121filters, or search criteria. In this way it can be used
122for simple lists or to search for contact records and their
123identifiers. The optional search criteria includes:
124
1251. start - Start at this identifier (integer: default 0)
126
1272. limit - Limit to this number of records returned(integer:
128  unlimited by default)
129
1303. fieldlist - limit to showing only these fields (array:
131  default to identifier, owner identifier, possibly firstname
132  and lastname)
133
1344. filter - Show records that are public or private only,
135  or other system-specific filters, e.g group or company(string:
136  default '')
137
1385. query - Search internal fieldlist for a value (string:
139  default '')
140
141The return for this method includes:
142
1431. count of number of records returned(integer)
144
1452. array consisting of: array: identifier => (array: fieldlist
146  key => value pairs)
147
148* read
149
150Once the identifier for a single contact record is known,
151the contact may be read for more detail using this method.
152This takes two parameters:
153
1541. identifier - (integer: no default)
155
1562. fieldlist - limit to showing only these fields (array:
157  default to identifier, owner identifier, possibly firstname
158  and lastname)
159
160And returns:
161
1621. array consisting of: array: identifier => (array: fieldlist
163  key => value pairs)
164
165* save
166
167This is a method used to save an existing record or create
168a new one. If the identifier for an existing record is not
169passed, a new entry will be created.
170
171* delete
172
173This will allow deletion of a record by passing its identifier.
174
1752.2.2 Schedule
176
1772.2.3 Notes
178
1792.2.4 Todo
180
1812.3 Examples in XML-RPC
182
183Query the contacts service for read_list, using only start
184and limit to grab the first 5 records, starting with identifier
1851. Additionally, return only the firstname and lastname
186fields n_given and n_family (firstname and lastname in pseudo
187vcard format):
188
189<methodCall>
190
191<methodName>service.contacts.read_list</methodName>
192
193<params>
194
195<param>
196
197<value><struct>
198
199<member><name>start</name>
200
201<value><string>1</string></value>
202
203</member>
204
205<member><name>limit</name>
206
207<value><string>5</string></value>
208
209</member>
210
211<member><name>fields</name>
212
213<value><struct>
214
215<member><name>n_given</name>
216
217<value><string>n_given</string></value>
218
219</member>
220
221<member><name>n_family</name>
222
223<value><string>n_family</string></value>
224
225</member>
226
227</struct></value>
228
229</member>
230
231<member><name>query</name>
232
233<value><string></string></value>
234
235</member>
236
237<member><name>filter</name>
238
239<value><string></string></value>
240
241</member>
242
243</struct></value>
244
245</param>
246
247</params>
248
249</methodCall>
250
2513 Conclusion
252
253This document outlined the following services and methods:
254
2553.1 Contacts:
256
257* service.contacts.read_list([search criteria])
258
259* service.contacts.read(identifier,[fieldlist])
260
261* service.contacts.save(fields)
262
263* service.contacts.delete(identifier)
264
2653.2 Schedule:
266
267* service.schedule.read_list([search criteria])
268
269* service.schedule.read(identifier,[fieldlist])
270
271* service.schedule.save(fields)
272
273* service.schedule.delete(identifier)
274
2753.3 Notes:
276
277* service.notes.read_list([search criteria])
278
279* service.notes.read(identifier,[fieldlist])
280
281* service.notes.save(fields)
282
283* service.notes.delete(identifier)
284
2853.4 Todo:
286
287* service.todo.read_list(search criteria)
288
289* service.todo.read(identifer,[fieldlist])
290
291* service.todo.save(fields)
292
293* service.todo.delete(identifier)
Note: See TracBrowser for help on using the repository browser.