Gallery3:Remote API (Deprecated) - Gallery Codex
Personal tools

Gallery3:Remote API (Deprecated)

From Gallery Codex

Deprecated

Please go to Gallery3:API:REST

Overview

With Gallery3, there is a need for a simplified and standardized remote API. Originally, some of the core controllers in Gallery3 were built as a RESTful API. Several issues resulted from this approach, mainly it added complexity and was not applied consistently. The code supporting this approach has been removed as part the RC1 release.

The basis of the Gallery3 Remote API will be an extensible RESTful implementation. Each user will have a remote access key assigned to their user id. Remote clients will provide the user id and password and and receive the access key back. Subsequent calls via the remote interface must provide this key to establish the identity of the requesting user.

Every request is atomic, in that no state is maintained across each request.

Authentication

Each user has a remote access key that corresponds to their user id. This access key is created when the user is created, the first time the user profile is accessed or the first time they login. This key can be requested by the remote client by supplying the user id and password. The access key is used to establish the active user for each remote request. Requests that do not contain an access key use the "guest" user as the active user.

Permissions

Permissions are assigned based on the user that created the shared secret. Any unsigned requests or anonymous requests will be treated as a public request and will be assigned permissions consistent with the "Everybody" group.

Client Implementation

On the first request, the client must preform a login to acquire the remote access key. The client provides the user id and password and upon return will receive the access token. It is expected that the client will not store the user id and password, but can and will store the access token for subsequent use.

Protocol

The Gallery3 remote protocol is based on the HTTP protocol. Allowable HTTP methods are GET, POST, PUT, DELETE.

Method Description
GET Retrieve a resource
PUT Update a resource
POST Add a new resource
DELETE Remove the resource

The remote protocol is implemented by the rest module. The basic URL to invoke a service is: <gallery3 domain name>/index.php/rest/<module>/<resource path>.

Gallery 3 Specific Headers

Header Description
X_GALLERY_REQUEST_KEY Specify the access key that identifies the user for this request.
X_GALLERY_REQUEST_METHOD Used to override the HTTP method. Typically used to provide PUT or DELETE functionality if the HTTP PUT or DELETE are blocked or unavailable.

Services

Albums and Photos

Get

Request

gallery3/index.php/rest/gallery/<resource>?limit=nnn&offset=nnn

Response

Post

Request

gallery3/index.php/rest/gallery/<resource>

Response

Put

Request

gallery3/index.php/rest/gallery/<resource>

Response

Delete

Request

gallery3/index.php/rest/gallery/<resource>

Response

Image Block

Get

Request

gallery3/index.php/rest/image_block?type=random

Response

Tags

Get

Request

gallery3/index.php/rest/tag/<resource>|<tag list>?limit=nnn&offset=nnn

Response

Post

Request

gallery3/index.php/rest/tag/<tag list>
post fields: path=<resource path>

Response

Put

Request

gallery3/index.php/rest/tag/<tag>
post fields: new_name=<new tag>

Response

Delete

Request

gallery3/index.php/rest/tag/<tag list>

Response