Labnotes

1. Aug 16th, 2007

   The Simple Publishing Protocol

   Ernest Prabhakar in the rest-discuss mailing list:

   I would love to see someone define/build a hAtom version of AtomPub, that worked in standard web browsers.

   Here’s one way to not make friends or influence people.
   Deep breath.

   The Simple Publishing Protocol

   The Simple Publishing Protocol describes a mechanism for retrieving a collection of entries or individual entries, and for publishing and editing entries, as is commonly present in Blogs, photo and video sharing sites, social networks, and other Web 2.0 wonderkids.

   The goals of the Simple Publishing Protocol:

   1. To provide a uniform mechanism for publishing and consuming collections of rich media,
   2. Support the Web Browser stack, and
   3. Do the simplest thing that could possibly work.

   Retrieving Entries

   The client makes a GET request to a known URL containing an entry or collection of entries, requesting a presentation in any content type suitable to the client.

   For the purpose of this discussion, we refer to content types compatible with (X)HTML (text/html, application/xhtml+xml, etc). Other content types will be covered in SSP: Adjuncts. Clients are allowed to guess the returned content type.

   The resulting representation will contain:

   1. Optional, one link identified by the relation new_entry (rel=”new_entry”).
   2. Zero or more entries identified according to the hAtom specification.
   3. Optional, for each entry one link identified by the relation edit_entry (rel=”edit_entry”).

   Adding an Entry

   The client may make a GET request to the new_entry URL, requesting a representation for the purpose of creating a new entry. Typically the request will be for an HTML content type for display in a Web browser.

   The client may make a POST request to the new_entry URL in order to create a new entry. The request may include, but is not limited to the following fields:

   1. title — string of text used for the title of the entry.
   2. content — the content of the entry (see below).
   3. author — URL identifying the author of the entry (recommended: the author’s OpenID identity URL).
   4. status — the status, either ‘published’ or ‘draft’ (default is ‘draft’).

   The client may send content in any media type supported by the server, as described in the hForm protocol. If the media type is unspecified, for example, when using application/x-www-form-urlencoded, the server interprets the content as text. The server may render content in a different format, for example, accepting Markdown content and for rendering as HTML.

   The server may return any applicable HTTP status code. If the server returns the HTTP status 303 (See Other), the client may assume that the Location header refers to the edit_entry URL associated with the new entry.

   Changing an Entry

   The client may make a GET request to the edit_entry URL, requesting a representation for the purpose of changing an existing entry. Typically the request will be for an HTML content type for display in a Web browser.

   The client may make a POST request to the edit_entry URL in order to change an existing entry. The request may include any field allowed when creating a new entry. The server may not change the value of any field unless that field appears in the request, or its value is derived from another field appearing in the request.

   The server may return any applicable HTTP status code.

   Deleting an Entry

   Follow the same procedure as when changing an entry, but set the status field to the value ‘delete’. The server will ignore all other fields in the request.

   The server may return any applicable HTTP status code.

   Authentication

   See here.

   Endnote that should come first: This “spec” was written in all of fifteen minutes, so you’ll have to excuse the brief writing style, narrowing down of the editable fields set, and the general lack of references, appendixes, or any examples of over-the-wire messages. The SPP working group will address these matters in due time.

   Second endnote: No envelopes were harmed in the production of this specification.

   Posted by Assaf Filed in general 10 Comments »

   1. Aug 17th, 2007

      Turulcsirip – Gábor

      [...] like: http://blog.labnotes.org/2007/08/16/the-simple-publishing-protocol/ « elÅ‘zÅ‘ | Gábor — 2007. 08. 17. [...]

   2. Aug 17th, 2007

      Eric Allam

      Using POST on new_entry and to create a new entry and POST on edit_entry to edit an entry breaks the Uniform Interface. You would want to edit an entry by PUTing to the entry resource URI. As it stands now SPP isn’t RESTful, but I like the idea of a super-simple publishing protocol using microformats.

   3. Aug 17th, 2007

      Assaf

      For publishing content, I just want something that works in the browser. Unfortunately the only thing uniform about browsers is that they can follow links and post forms, but I think it’s an acceptable tradeoff.

   4. Aug 17th, 2007

      Labnotes » One line publishing

      [...] Publishing a blog post using SPP: [...]

   5. Aug 17th, 2007

      FatMixx » Blog Archive » Labnotes » One line publishing

      [...] the perfect definition for my idea of a perfect HTTP-based web service. SPP looks like a good idea… (click here for the original story) Tags: programming style, [...]

   6. Aug 17th, 2007

      Eric Allam

      “For publishing content, I just want something that works in the browser. Unfortunately the only thing uniform about browsers is that they can follow links and post forms, but I think it’s an acceptable tradeoff.”

      Then why the curl one-liner?

   7. Aug 17th, 2007

      Assaf

      The curl one-liner is a proof of simplicity.

      That’s something that applies to RESTful interfaces as well, you can use curl one-lines to find simplicity in PUT and DELETE request as well.

   8. Aug 20th, 2007

      Gabe

      AFAIK, PUT is for creating a resource at the specified URI (that the client specifies), and POST is for sending data (which may create a “resource” at some other URI not specified by the client)

   9. Aug 20th, 2007

      Assaf

      Or you can use PUT to update an existing resource.

   10. Aug 20th, 2007

       Chipping the web – trees of ten — Chip’s Quips

       [...] How to lick the envelope. [...]