Gallery3:API:REST

From Gallery Codex

Disclaimer and Design Planning

G3 REST is under development. This document discusses plans for functions and features that may or may not ever be available. If you want to affect the design and deployment of G3REST, please join and discuss in gallery-devel.

Feedback on these points is urgently needed:

The URI model and the provided operations.
Connectedness. Is this something that you would care about when

writing a client?

Resource Representation/Data format.

Is JSON good enough? Is Atom too complicated? I see two options:

1. Spend significant resources on writing our Atom library and

implementing Atom feeds and entries.

2. Use JSON everywhere, even where we would have used XML. Try to

design the data structures in a way that would make it possible to adapt to Atom in a future version. If we go with this option, it is entirely possible that we will never support Atom because clients will already have been written for JSON and there would have to be a real killer use case for Atom for us to implement it.

Intro to Gallery3 REST

Gallery3 will expose a REST(or RESTful)[1] API.

In a nutshell, REST interfaces interact with resources (in the case of Gallery, photos, albums, comments) through standard HTTP requests and responses where every resource is identified by a URI. Because all API 'calls' are URIs, the interface is easier to use and understand for folks with limited "programming" skills. Yet it can be just as powerful and 'full' as any more 'programmatic' API.

The current model implements a single controller for each type of resource that we want to expose. Often these will be collections of resources (albums, photos), but sometimes not (slideshow). Following is a list of operations our model allows. The current examples focus on operations on collection-type resources (albums, photos, comments), being the most commonly used in Gallery, but the REST infrastructure can certainly be also used for non-collection type resources (e.g. slideshow).

Unformatted Design Notes

G3REST OPerations

Find data

GET /{controller_name} with an optional query string Used to get all items in a collection, or only a subset that is defined by the query string. Results are returned in the response body.

Example: GET /comments returns all comments GET /comments?item_id=2 returns all comments attached to photo 2

Add new data

POST /{controller_name} Adds a new item to the collection. Item meta data is defined in the request body.

Example: POST /comments Adds a new comment.

Delete data

DELETE /{controller_name}/{item_id} Deletes the specified item from the collection.

Example: DELETE /comments/3 Deletes the comments that has an id of 3.

Update existing data

PUT /{controller_name}/{item_id} Updates an existing item with the specified id. The changes are specified in the request body.

Display HTML forms

The API supports add and edit forms for every controller. We make it very easy to add validation to forms, and they are actually not PUT (in the case of edit) or POSTed (in the case of add) until the form is declared valid.

GET /form/edit/{controller_name}/{item_id} Returns a HTML form in the response body that is populated with item meta data. It is set up to PUT the submitted data to /{controller_name}/{item_id}.

GET /form/add/{controller_name} with optional arguments Returns an empty form for adding a new item to a collection. The results are POSTed to /{controller_name}

Examples: GET /form/edit/comments/2 GET /form/add/comments/4 In the second case 4 is the item id of the photo the comment is being added to. We may make this more clear by replacing /4 with ?item_id=4. You can try this out right now in G3, just make sure that the comment/item ids exist.

I wrote some more examples in the spreadsheet[2] I'm working on. It is a work in progress and probably contains inconsistencies and will change as we make progress. I'm confident that this model will work for the vast majority of use cases, but I'd like to hear examples from you where you think this breaks down so we can take them into account.

Resource Representation

The other area we'd like to hear from you is regarding resource representation, i.e. how resources should be represented in the request and response bodies. For now, let's ignore binary data such as photos, as there are good solutions for that which do not depend on what representation we choose for the meta data. We can talk about it in a different thread if someone wants to.

I'd also like to mention connectedness (as some authors call it) in the context of REST. It basically means that resource representations should contain links to other resources. This allows the server to guide clients from one application state to another. In the context of Gallery, this means that a GET on /photos/23 would also return links to the previous photo, next photo, parent album, comments associated with the photo, etc. A GET on /comments/56 would include a link to the parent photo. As you can imagine, this would form a web of links that clients can follow, and a well implemented RESTful web service should provide them.

Resources can also have multiple representations, e.g. JSON, XML, HTML, Atom. By default, we return HTML and that is what you see when you visit Gallery with your browser. The Gallery API also defines what types of representations it accepts. I think that's enough theory, now lets get down to practical questions.

We started out with providing JSON and XML. The idea was that JSON would be used for Ajax communication with the browser, and we'd provide an XML representation for third-party clients. As we do not want to reinvent the wheel by coming up with our own XML, the natural choice seemed to be Atom. It is well-suited for representing collection-type resources and providing related links. There are also very good examples of this approach on the web, such as GData[3]. The downside is that I haven't been able to find any good libraries in PHP that would both read and write Atom feeds and entries. So we'd have to write our own. Also, we're not sure that developers who would use our API would actually find it easy to work with Atom. Clients they write would have to both read it in responses from the server and send it in requests to the server. At the end of the day, we want to make it easy for developers to communicate with Gallery, and we're not actually sure that this is easy for them.

Another route we can take is to forget XML and Atom and just go with JSON. We will implement it into most controllers since it's the natural way to communicate with Ajax clients, one which is Gallery itself. JSON is widely supported and we should be able to encode all of the data we would have used Atom for, including links.

To recap,