Gallery Remote Protocol version 1

Tim Miller <tim_miller at users dot sourceforge dot net>

This document describes the gallery remote application protocol, which is layered over HTTP, as of version 1.3.1 of gallery.


Summary

Gallery remote queries and sends information from a gallery installation through a protcol based on HTTP and form-data. The protocol leverages the same user authentication (and session cookies) as the web/HTML interface to the site. It is implemented in one PHP source file, gallery_remote.php.

Every query from client to server corresponds to one action. Multiple actions require multiple HTTP requests.

The protocol is stateful; the client must acquire the gallery session cookie by performing a login request before any other requests will succeed.

Permissions for actions performed by gallery_remote.php are controlled in the same way they are controlled for regular web/HTML users. init.php is called at the top of each request.


Requests

Each request is expressed through an HTTP POST -- parameters are expressed as HTTP form data (control-name/current value) pairs (we'll call them "key" and "value").

Each request specifies a command (the "cmd" key). Depending on which command is specified, other parameters are required in the form-data set.

Each request also specifies a protocol version (the "protocal_version" [sic] key). If the protocol version specified by the client does not match exactly $gallery->remote_protocol_version, the request is declined. The current protocol version is "1" (it has never been changed).

Each command is described below. After a brief description of the command, template form data appears and the result format (if any) is described.


Notes

The results sections below assume a HTTP 200 OK status code was returned, although a 4xx or 5xx result is possible. Additionally, if the protocol version is not correct, regardless of the command, an English textual error message is returned, with no other results.


Commands

Note:The word "protocol" is misspelled in the "protocal_version" key.

  1. login command

    This command ensures a session cookie has been given to the client and, if the account information is correct, adds the proper user object to the session.

    • Context

      A request with the login command may be made at any time -- there are no prerequisites.

    • Form Data

      cmd=login
      protocal_version=1
      uname=
      gallery user name
      password=
      cleartext password

    • Results

      If the login succeeds, the value

      SUCCESS

      is returned. If the login fails, the value

      Login Incorrect

      is returned. If either the uname or password keys are missing, the value

      Missing Parameters

      is returned.

  2. fetch-albums command

    The fetch-albums command asks the server to return a list of all albums (visible with the client's logged in user permissions).

    • Context

      A request with the login command must be made before the fetch-albums command is used.

    • Form Data

      cmd=fetch-albums
      protocal_version=1

    • Results

      If successful, the a request using the fetch-albums command returns tab- and newline-delimited data. Each line consists of an album name, a tab character, the album title and a newline, except the last line which will contain the value

      SUCCESS

      If the "SUCCESS" value is not present, the list of albums should not be considered complete and the request to have failed.

  3. add-item command

    This command asks the server to add a photo to a specified album.

    • Context

      A request with the login command must be made before the add-item command is used.

    • Form Data

      cmd=add-item
      protocal_version=1
      set_albumName=
      album name
      userfile=
      form-data-encoded image data

    • Results

      If the file upload succeeds the value

      SUCCESS

      is returned. If the file upload fails, a line beginning with the value

      ERROR:

      and followed by an English-language description of the reason is returned.