This document describes version 3 of the Gallery remote application protocol, and its minor revisions.
This version is only supported on Gallery 2 (G2) and is based on a Web Services framework.
Revision: $Id: protocol3.xml,v 1.4 2004/08/11 17:33:21 paour Exp $
We want to make it easy to develop simple clients, but also support clients that need fine-grained control.
We also need to keep bandwidth under control and not send unnecessary data. Also, we should try to transport images in compressed format (8-bit), rather than the verbose Base64.
We should not expose data that's not supposed to be available based on the auth. The G1 protocol doesn't comply with that.
In order to minimize protocol latency and bandwidth, most frequently-used tasks should be implemented as single large requests, rather than a collection of small requests. For example, setting properties on an item should be done in one request rather than as many requests as properties to be set.
For maximum flexibility, the protocol should probably not use a highly typed object model (ala SOAP/XML Schema), but rather a loosely-typed model.
Token names should be consistent both with G2 naming, and between the different requests.
This will probably rely on built-in error support in the chosen protocol.
G2 has framework-level support for handling this, we just need to make sure we accurately report errors that arise from concurrent modification, and that we pass serial numbers around.
As much as possible, we should make it possible to address not only core features, but also modular features, such as getting the list of comments, exif, customfield, etc. for an item.
This will be an evolving protocol; versioning should be supported in the form of protocol version numbers.
Additionally, the protocol should support querying for availability of a given feature.
This section is under active discussion; nothing is set.
This should return item data. Depending on the request, one or many items can be returned. G2 items are all associated with item ids and all inherit from a basic Entity object, with various extensions. This method can fetch items of any type, with as much or as little information about each item.
Although this method is generic, some special handling may be added for some item classes, such as pictures, to add transient data, such as the URL where the image data can be found, etc.
selectionType: one of the following:
childrenOf: selectionData is a list of ids of parents, will return all children of these parents, as long as the children pass the other filters.
childrenOfRecursive: selectionData is a list of ids of parents, will return all descendants of these parents, as long as the descendants pass the other filters.
items: selectionData is a list of ids, will return all these items, as long as they pass the other filters.
selectionData: see above.
permissionList (optional): a definition of which permissions must be available to the current user for a given item to be included in the reply. The definition is a list of comma-separated permission names (like core.addAlbumItem). By default, all readable items are returned.
permissionType (optional): either and or or. Depending on this, items will be returned if they match all the permissions or any permission. By default, or.
includeTypes (optional): a list of item types that items need to be of in order to be included in the reply. By default, all item types are returned.
excludeTypes (optional): a list of item types that items must not be of in order to be included in the reply. By default, no item types are excluded.
memberNames (optional): a list of the names of members/proprties that will be returned. For each selected item, only members the names of which appear on this list will be returned. The item id and serialNumber are always returned. If this parameter is not present, all members are returned.
This parameter serves to restrict the size of the returned data stream.
The naming of members should reflect the native G2 naming of the members/properties. However, meta member names will likely need to be created for transient data (data that is generated at runtime and not available in the DB) or aggregate data.
wellFormedTree (optional): if set to TRUE, parents of selected items will also be included in the reply, even if they do not match the other query filters (they should still be readable by the client). By default, a sparse tree is returned (potentially not well-formed).
maxItemNumber (optional): if set, will only return the first n items. This is to prevent the protocol from returning huge lists of results. This would be mostly useful when getting the list of pictures in an albu, recursively.
An array of items is returned. Depending on the protocol being used, this can be loosely typed (ie: value-pairs) or strongly typed (ie: defining classes for each of the possible return types in WSDL or a similar system). This is not yet defined.
This request fetches the list of all albums in which the user can add media.
HTTP POST request, with the following parameters:
username=paour password=toto selectionType=childrenOfRecursive selectionData=root permissionList=core.addDataItem,core.addAlbumItem includeTypes=GalleryAlbumItem memberNames=id,serialNumber,parentId,pathComponentdescription,summary,title,orderWeight wellFormedTree=TRUE
itemCount=3 item.1.id=6 item.1.serialNumber=6 item.1.parentId=0 item.1.pathComponent= item.1.description=This is the top of your Gallery item.1.summary= item.1.title=Gallery item.1.orderWeight=0 item.2.id=9 item.2.serialNumber=1 item.2.parentId=6 item.2.pathComponent=album1 item.2.description=My first album item.2.summary= item.2.title=Album1 item.2.orderWeight=0 item.3.id=12 item.3.serialNumber=2 item.3.parentId=6 item.3.pathComponent=album2 item.3.description=I changed this item.3.summary= item.3.title=My second album item.3.orderWeight=1000 status_code=0
This should be possible both in SOAP/XML-RPC (Base-64) and HTTP POST (binary). Both versions should be very simple, with as little data being sent beside the media data and which album to put it in. The reply should contain the item id of the new media item.
G2's addItemToAlbum method requires the media file, name, title, summary, description and mime-type. Do we need to provide all this in this request?
One of the below:
Image data; depending on the format (SOAP/XML-RPC) or HTTP POST, the data will be Base-64 encoded or not.
A URL to the image data, which G2 will then retrieve. The advantage is this method doesn't run afoul of PHP's memory and upload limits, but the data needs to be somewhere where the server can get at it.
parentAlbum: the id of the album the media should be placed in.
Similarly to uploading an image, this should be a simple creation that returns the item id, followed by another query to set the item's properties.
This could also be used to create generic items, if there's a need for it.
This is the setter corresponding to the getItem request. In order to maximize backward compatibility and minimize protocol chatter, only members that need to be updated should be passed in the query.
item: the id of the item to update.
a list of name-value pairs for the members to update. In the event we want a typed protocol, an object with only some fields provided. This means we would have an object model where each field is optional.
This moves the item from its current parent to a different parent. Probably only useful for children of an album.
This deletes an item. Probably only useful for children of an album.
This method reorders the items within an album (probably no other uses).
Internally, G2 stores orderWeights to determine the order in which items within an album are stored; this allows an album to be sorted by orderWeight or other parameters dynamically, while retaining the "natural order" (G2 UI calls this "no sort order") of the orderWeights. This method only applies to the orderWeights. Should we expose the orderWeights in the protocol or just expose "natural order" sequence numbers?
Caveat: for G2, the orderWeight is a property of the item, whereas order is a property of the container. This is likely to cause ambiguities with permissions.
item: the id of the item to reorder.
newOrder: the ordered list of children. The pre-existing order will have been obtained with a getItem request.
This method increments the viewCount and updates the viewedSinceTimestamp of a item.