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
Responses
Response format is determined by the HTTP Accept header. 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.
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 XXX
/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. 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 XXX
/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. XXX
DELETE: Delete the media item.
Implementation Ideas
- 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.