REST API - Revision history

Nyergler: /* Implementation Thoughts */

2012-02-04T22:05:39Z

Implementation Thoughts

← Older revision		Revision as of 22:05, 4 February 2012
Line 83:		Line 83:
	== Implementation Thoughts ==		== 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.		* 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.		* Codec classes for encoding/decoding; see [https://docs.djangoproject.com/en/1.3/topics/serialization/ Django Serializers] for inspiration.

Nyergler: /* Further Reading */

2012-02-04T22:03:31Z

Nyergler: /* Overview */

2012-02-04T22:03:06Z

Overview

← Older revision		Revision as of 22:03, 4 February 2012
Line 10:		Line 10:
	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).		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).		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 ===

	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:		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>		<code>Accept: application/json</code>
Line 20:		Line 20:
	Initially MGS will support JSON, but other formats such as YAML, XML, or RDF may be added.		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.		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:		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:

Nyergler: /* Supported Endpoints */

2012-02-04T22:01:57Z

Supported Endpoints

← Older revision		Revision as of 22:01, 4 February 2012
Line 34:		Line 34:
	GET: Return information about the user, including website and bio.		GET: Return information about the user, including website and bio.

	~~POST~~: Update the user's information		PUT: Update the user's information.

	===/u/<username>/gallery/===		===/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.		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.

	~~PUT~~: Upload a new media item for this user. The response ~~will~~ contain the Location: header, which is the URI for the new resource.		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>===		===/u/<username>/m/<slug>===

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

	~~POST~~: ~~Update~~ the ~~media item, possibly updating the~~ metadata ~~or replacing~~ the media ~~file.~~		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.		DELETE: Delete the media item.

Nyergler: /* Overview */

2012-02-04T21:56:19Z

Overview

← Older revision		Revision as of 21:56, 4 February 2012
Line 8:		Line 8:
	== Overview ==		== 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).		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 ===

Nyergler: /* Overview */

2011-11-14T01:31:07Z

Overview

← Older revision		Revision as of 01:31, 14 November 2011
Line 8:		Line 8:
	== Overview ==		== 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~~.		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 ===
Line 19:		Line 19:

	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.		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 ==		== Supported Endpoints ==

Nyergler at 01:27, 14 November 2011

2011-11-14T01:27:28Z

← Older revision		Revision as of 01:27, 14 November 2011
Line 77:		Line 77:
	* HTTP verb based dispatch wrappers for views would allow us to map different verbs to different views.		* 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.		* 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

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

2011-11-14T01:19:31Z

/u//gallery/

← Older revision		Revision as of 01:19, 14 November 2011
Line 34:		Line 34:
	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.		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		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>===		===/u/<username>/m/<slug>===

Nyergler: /* Media */

2011-11-14T01:18:45Z

Media

← Older revision		Revision as of 01:18, 14 November 2011
Line 71:		Line 71:
	* description		* description
	* owner		* owner
	* resource (~~URL~~ of the media)		* resource (GET specific; URI of the media file)

	== Implementation Thoughts ==		== Implementation Thoughts ==

Nyergler: /* User */

2011-11-14T01:16:30Z

User

← Older revision		Revision as of 01:16, 14 November 2011
Line 54:		Line 54:
	* biography		* biography
	* website		* website
			* gallery (location for retrieving a list of media resources)

	=== Gallery ===		=== Gallery ===

← Older revision		Revision as of 22:03, 4 February 2012
Line 90:		Line 90:
	* http://blog.steveklabnik.com/2011/07/03/nobody-understands-rest-or-http.html		* 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://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