REST API

This document is a draft describing a 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. OAuth2 should be considered a baseline.

Requests

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

Accept: application/json

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

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

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.

POST: Update the user's information

/u/<username>/gallery/

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

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

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

GET: Retrieve the full metadata about the media, including URIs for media files.

POST: 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

• HTTP verb based dispatch wrappers for views would allow us to map different verbs to different views.
• Codec classes for encoding/decoding; see Django Serializers for inspiration.