6. Gallery Remote Protocol for G2

6.1. Introduction
6.2. Design guidelines
6.2.1. Statelessness
6.2.2. Scalability
6.2.3. Security
6.2.4. Granularity
6.2.5. Typing
6.2.6. Consistency
6.2.7. Robust error management
6.2.8. Concurrent modification management
6.2.9. Compatibility with modules
6.2.10. Versioning
6.2.11. Chained requests
6.3. Methods
6.3.1. getItem
6.3.2. addMedia
6.3.3. createAlbum
6.3.4. setItem
6.3.5. moveItem
6.3.6. aliasItem
6.3.7. copyItem
6.3.8. deleteItem
6.3.9. reorderChildren
6.3.10. incrementViewCount
6.3.11. Media manipulation
6.3.12. User management

6.1. Introduction

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 $

6.2. Design guidelines

6.2.1. Statelessness

Auth is passed with every request

6.2.2. Scalability

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.

6.2.3. Security

We should not expose data that's not supposed to be available based on the auth. The G1 protocol doesn't comply with that.

6.2.4. Granularity

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.

6.2.5. Typing

For maximum flexibility, the protocol should probably not use a highly typed object model (ala SOAP/XML Schema), but rather a loosely-typed model.

6.2.6. Consistency

Token names should be consistent both with G2 naming, and between the different requests.

6.2.7. Robust error management

This will probably rely on built-in error support in the chosen protocol.

6.2.8. Concurrent modification management

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.

6.2.9. Compatibility with modules

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.

6.2.10. Versioning

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.

6.2.11. Chained requests

SOAP allows more than one request in the same envelope. We should use that to support transactions.

6.3. Methods

This section is under active discussion; nothing is set.

6.3.1. getItem

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.

6.3.1.1. Input
  • 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.

6.3.1.2. Output

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.

6.3.1.3. Examples
6.3.1.3.1. Java preferences (like G1 protocol)

This request fetches the list of all albums in which the user can add media.

Input

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
	    
Output
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
	    
6.3.1.3.2. SOAP

This request fetches the list of pictures inside an album for a slideshow.

6.3.2. addMedia

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?

6.3.2.1. Input
  • 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.

6.3.2.2. Output

The id of the newly created media.

6.3.3. createAlbum

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.

6.3.3.1. Input

Optionally, item class. If none is provided, an album is created.

6.3.3.2. Output

The id of the newly created album.

6.3.4. setItem

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.

6.3.4.1. Input
  • 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.

6.3.4.2. Output

No data output.

6.3.5. moveItem

This moves the item from its current parent to a different parent. Probably only useful for children of an album.

6.3.5.1. Input
  • item: the id of the item to move.

  • moveTo: the id of the new parent.

6.3.5.2. Output

No data output.

6.3.6. aliasItem

Similar to moveItem, maybe should be the same method with a flag?

6.3.7. copyItem

Similar to copyItem, maybe should be the same method with a flag?

6.3.8. deleteItem

This deletes an item. Probably only useful for children of an album.

6.3.8.1. Input
  • item: the id of the item to delete.

6.3.8.2. Output

No data output.

6.3.9. reorderChildren

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.

6.3.9.1. Input
  • 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.

6.3.9.2. Output

No data output.

6.3.10. incrementViewCount

This method increments the viewCount and updates the viewedSinceTimestamp of a item.

6.3.10.1. Input
  • item: the id of the item to increment.

6.3.10.2. Output

No data output.

6.3.11. Media manipulation

Rotation/resizing of media is outside the scope of the initial version.

6.3.12. User management

User management is outside the scope of the initial version.