View source for REST API

This document is a draft describing a [https://secure.wikimedia.org/wikipedia/en/wiki/REST REST] API for interacting with MediaGoblin servers.

== Principles ==

* Leverage HTTP where possible
* Allow clients to "follow their nose"

== Overview ==

Clients access MediaGoblin Servers (MGS) using HTTP to retrieve, upload, and update media. Some operations are available to unauthenticated users (for example, getting media details in a default configuration). Others require that the User authorize the client application (CA). 

When authorization is required, a User MUST authorize the CA using a supported authorization method. What authorization methods are supported is unspecified at this point. HTTP Basic is easy, OAuth2 feels like a better choice (and will require more work).

=== Requests ===

Requests MUST specify the HTTP Accept header to indicate the preferred response format. A client that wishes to receive a JSON-formatted response, for example, will send the header:

<code>Accept: application/json</code>

Initially MGS will support JSON, but other formats such as YAML, XML, or RDF may be added.

When updating or creating resources, fields MUST be query string encoded as the request body. When uploading media, the request MUST be a multipart request, with the metadata and file both provided.

Client applications MUST specify a User-Agent which identifies the client and provides a URL where information about the client can be found. For example:

<code>User-Agent: MediaGoblin for Android v0.0.0.0.1 (http://mediagoblin.org/android)</code>

== Supported Endpoints ==

The following is a list of URL endpoints which should support content negotiation for the purposes of supporting non-browser client applications. HTTP verbs other than those listed will return HTTP 405 (method not supported).

=== /u/<username> ===

GET: Return information about the user, including website and bio.

PUT: Update the user's information. 

===/u/<username>/gallery/===

GET: Return a list of media owned by the user. Each returned element MUST include a title, creation date, edit date, and canonical URL for the resource. If more than a single "page" is available, the <code>Link:</code> header SHOULD be provided with <code>rel="next"</code>. Subsequent pages SHOULD also include a <code>rel="prev"</code> link, to allow for navigation.

POST: Upload a new media item for this user. The response MUST contain the Location: header, which is the URI for the new resource.

===/u/<username>/m/<slug>===

HEAD: Retrieve minimal metadata about the media

GET: Retrieve the full metadata about the media

PUT: Update the media item, possibly updating the metadata or replacing the media file.

DELETE: Delete the media item.

== Supported Properties ==

The following properties are "keys" which can be looked for when retrieving a resource, or specified when updating or creating one. Additional properties may be present when retrieving resources, and Client Applications MUST NOT consider their presence an error state.

=== User ===

* username
* email
* biography
* website
* gallery (location for retrieving a list of media resources)

=== Gallery ===

* media-item
** location
** title
** created
** edited

=== Media ===

* title
* created
* updated
* description
* owner 
* resource (GET specific; URI of the media file)

== Implementation Thoughts ==

* Views may be built as classes, with method conventions for specific response types (GET).
* HTTP verb based dispatch wrappers for views would allow us to map different verbs to different views.
* Codec classes for encoding/decoding; see [https://docs.djangoproject.com/en/1.3/topics/serialization/ Django Serializers] for inspiration.

== Further Reading ==

* http://blog.steveklabnik.com/2011/07/03/nobody-understands-rest-or-http.html
* http://blog.steveklabnik.com/2011/08/07/some-people-understand-rest-and-http.html
* http://stackoverflow.com/questions/1619152/how-to-create-rest-urls-without-verbs/1619677#1619677