GNU MediaGoblin Wiki - User contributions [en]

REST API

2012-02-04T22:05:39Z

Nyergler: /* Implementation Thoughts */

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

REST API

2012-02-04T22:03:31Z

Nyergler: /* Further Reading */

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 ==

* 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

REST API

2012-02-04T22:03:06Z

Nyergler: /* Overview */

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 ==

* 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

REST API

2012-02-04T22:01:57Z

Nyergler: /* Supported Endpoints */

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

<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 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.

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 ==

* 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

REST API

2012-02-04T21:56:19Z

Nyergler: /* Overview */

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

<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 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.

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.

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 <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.

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 [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

REST API

2011-11-14T01:31:07Z

Nyergler: /* Overview */

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

<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 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.

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.

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 <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.

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 [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

REST API

2011-11-14T01:27:28Z

Nyergler:

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

<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 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 <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.

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 [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

REST API

2011-11-14T01:19:31Z

Nyergler: /* /u//gallery/ */

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

<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 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 <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.

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 [https://docs.djangoproject.com/en/1.3/topics/serialization/ Django Serializers] for inspiration.

REST API

2011-11-14T01:18:45Z

Nyergler: /* Media */

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

<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 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 <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.

PUT: Upload a new media item for this user

===/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 [https://docs.djangoproject.com/en/1.3/topics/serialization/ Django Serializers] for inspiration.

REST API

2011-11-14T01:16:30Z

Nyergler: /* User */

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

<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 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 <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.

PUT: Upload a new media item for this user

===/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 (URL of the media)

== 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 [https://docs.djangoproject.com/en/1.3/topics/serialization/ Django Serializers] for inspiration.

REST API

2011-11-14T01:15:42Z

Nyergler: /* /u//gallery/ */

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

<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 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 <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.

PUT: Upload a new media item for this user

===/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 ===

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

=== Media ===

* title
* created
* updated
* description
* owner
* resource (URL of the media)

== 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 [https://docs.djangoproject.com/en/1.3/topics/serialization/ Django Serializers] for inspiration.

REST API

2011-11-14T01:15:25Z

Nyergler: /* Gallery */

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

<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 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. 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.

PUT: Upload a new media item for this user

===/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 ===

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

=== Media ===

* title
* created
* updated
* description
* owner
* resource (URL of the media)

== 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 [https://docs.djangoproject.com/en/1.3/topics/serialization/ Django Serializers] for inspiration.

REST API

2011-11-14T01:15:02Z

Nyergler: /* Supported Properties */

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

<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 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. 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.

PUT: Upload a new media item for this user

===/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 ===

* media-item
** location
** title
** description

=== Media ===

* title
* created
* updated
* description
* owner
* resource (URL of the media)

== 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 [https://docs.djangoproject.com/en/1.3/topics/serialization/ Django Serializers] for inspiration.

REST API

2011-11-14T01:14:00Z

Nyergler:

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

<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 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. 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.

PUT: Upload a new media item for this user

===/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

=== Media ===

* title
* created
* updated
* description
* owner
* resource (URL of the media)

== 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 [https://docs.djangoproject.com/en/1.3/topics/serialization/ Django Serializers] for inspiration.

REST API

2011-11-14T01:08:30Z

Nyergler:

REST API

2011-11-14T00:25:11Z

Nyergler: Created page with "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" ..."

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 ==

== Media ==

=== Retrieving ===

=== Uploading ===