![[Home]](http://www.bayleshanks.com/cartoonbayle.png)
These are notes towards a protocol intended to compete with Atompub and WebDAV?. Here is a listing of features that the protocol defines, grouped into sets of features called "profile levels" for convenience:
In addition, the Blog/Wiki Basic Profile is defined as the following subset of features from out of those above:
This protocol is intended to have a short specification (at the expense of comprehensiveness), and to be easily implementable in a web application (i.e. server-side), provided that the web application can handle HTTP PUT and can control the headers issued by the server.
Here is a concise summary of the protocol itself.
The client asks for a listing:
GET / HTTP/1.1 Host: example.com Accept: text/uri-list2
The server provides one:
HTTP/1.1 200 OK Date: Wed, 25 Feb 2009 06:28:25 GMT Server: Apache/2.2.9 (Debian) Content-Length: 50 Content-Type: text/uri-list2 Available-Content-Types: text/html, text/uri-list2 http://example.com/item1 Item 1 http://example.com/item2 Item 2
The client creates a new document:
PUT /item3 HTTP/1.1 Host: example.com Content-Type: text/html Content-Length: 41 <html><body><h1>test3</h1></body></html>
The server says OK:
HTTP/1.1 201 Created Date: Wed, 25 Feb 2009 06:28:25 GMT Available-Content-Types: text/html;processed=0 Put-Accept: text/html, text/wiki-creole Content- Length: 0 Location: http://example.com/item3
The client replaces the document:
PUT /item3 HTTP/1.1 Host: example.com Content-Type: text/wiki-creole Content-Length: 9 **bold**
The server says OK:
HTTP/1.1 200 OK Date: Wed, 25 Feb 2009 06:28:25 GMT Available-Content-Types: text/html;processed=1, text/wiki-creole;processed=0 Put-Accept: text/html, text/wiki-creole Content- Length: 0 Location: http://example.com/item3
The client asks for the default representation:
GET /item3 HTTP/1.1 Host: example.com
The server provides it:
HTTP/1.1 200 OK Date: Wed, 25 Feb 2009 06:28:25 GMT Server: Apache/2.2.9 (Debian) Content-Length: 49 Content-Type: text/html Put-Accept: text/html, text/wiki-creole Available-Content-Types: text/html;processed=1, text/wiki-creole;processed=0 <html><body><strong>test3</strong></body></html>
The client asks for the source representation:
GET /item3 HTTP/1.1 Host: example.com Accept: text/wiki-creole;processed=0
The server provides it:
HTTP/1.1 200 OK Date: Wed, 25 Feb 2009 06:28:25 GMT Server: Apache/2.2.9 (Debian) Put-Accept: text/html, text/wiki-creole Content-Length: 8 Content-Type: text/wiki-creole Alternates: text/html;processed=1, text/wiki-creole;processed=0 **bold**
Different web applications will choose to implement different parts of this standard. For instance, an application exposing a read-only API might implement the features of listing a collection, server-advertised multiple representations of a document, search queries, and document-associated metadata, but not implement creation or updating of documents, whereas another application might implement creating, updating, listing, deletion of documents, server-advertised multiple representations, and versioning, but not search queries or metadata. Therefore, except when dependencies are explicitly stated, each feature of this standard may be thought of as a little standard of its own, and software may claim to comply with some features of this standard without asserting compliance with other features.
For convenience, this specification will use the word MUST when describing individual features; but this should be read as, "IF software implements this particular feature, THEN it MUST ...".
The "profiles" are merely useful abbreviations for the sake of human discussion; you can implement some features in a profile without implementing all of the others, and you can implement features in level 2x profiles without implementing profile level 1. To describe this, you speak in terms of individual features, rather than profiles.
However, if you do choose to speak in terms of profiles: to assert that software implements a profile means that it implements every feature in that profile, as well as every feature in every profile in the lower levels. So, if you say that X implements profile 2B, you are saying that it implements every feature in 2B as well as every feature in profile level 1.
To request a list of URIs from a collection URL, a client sends an HTTP GET request with an Accept header with value "text/uri-list2".
The server MUST respond with a document of Content-Type text/uri-list2, or an error message.
The format text/uri-list is defined in http://tools.ietf.org/html/rfc2483#section-5. Briefly, it is a set of lines, with each line either a comment (a line starting with '#'), or a URI. The format text/uri-list2 is the same, except that each URI might optionally be followed by a space, and then a title.
The server MAY offer other representations of the list at the collection URI, for example, an XML feed document that gives metadata about each URI on the list. If so, the client can use the Accept header to choose a representation type.
The following errors are required in case of the following situations:
| 404 Not Found | the URL does not exist | ||||
| 406 Not Acceptable | the URL is not associated with a collection |
If the URL is a collection URI, but the server does not associate it with a collection, then the server MUST reply with a 406. If the URL is a collection URI, but the collection is currently empty, then the server MUST reply with a 200 OK and an empty document.
The client should be aware that servers which do not follow this protocol might respond with error 406, or they might respond with a document which is not of type text/uri-list2.
See HTTP PUT.
See HTTP PUT.
If the client PUTs a document with a Content-Type that the target URI does not support, the server MUST issue an error 415 Unsupported Media Type.
In addition to the HTTP 1.1 status codes, the following status codes from WebDAV may be returned: 423 Locked, 422 Unprocessable Entity, 507 Insufficient Storage.
For URIs which make available multiple representations, a response to HTTP GET MAY contain the new header field Available-Content-Types whose value contains a comma-separated list of possibly parameterized mime-types of alternative representations which are available. Media type parameters MAY be included.
A type which is listed in Available-Content-Types MUST be returned upon a GET request with an Accept header field containing only that type. That is to say, a type advertised in Available-Content-Types MUST actually be available. However, other types may also be available which are not included in Available-Content-Types.
The type of the default representation, that is, the representation that the server will choose to send when it gets a GET request without an Accept header, SHOULD be the first element in the Available-Content-Types list.
If the server provides the Available-Content-Types header at some URL, then, regardless of whether a particular client has actually retrieved that header in the past, the server MAY choose to interpret Accept headers in GET requests to that URL in a simpler way than that given by the HTTP 1.1 spec, replacing that interpretation with the following one.
Each type in the comma-separated Accept header need only be recognized if, considered as a string, after whitespace is removed, it case-insensitively matches one of the values provided in the Available-Content-Types header, OR it case-insensitively matches at least one of the values provided in the Available-Content-Types header when the latter is stripped of parameters.
However, even if no types are recognized, if the Accept header contains the media type */*, then the server MUST serve its default document (just as if no Accept header was present).
If the server chooses not to parse other media ranges (for example, "text/*" or "*/html"), and especially if there are asterisks in the Accept header, the server should strongly consider serving its default representation rather than issuing a 406 Not Acceptable if it cannot recognize an Accept header. Otherwise, clients who request a media range which could have been satisfied will get a 406.
An example of where this interpretation differs from the HTTP 1.1 spec is as follows.
At URI X, the server may provide:
Available-Content-Types: text/html, text/plain;foo=0;bar=3, text/plain;foo=1;bar=3
If the client sends a request with:
Accept: text/plain;bar=3;foo=0
Then according to this protocol (but not according to HTTP 1.1), the server may act as if this were an unknown mime type (that is, it may reply with error 406, or it may reply with a representation of whatever type it chooses). The client was supposed to exactly string-match the choices given by the server, for example, this would have been recognized:
Accept: text/plain;foo=0;bar=3
However, the client is also permitted to simply send
Accept: text/plain
in which case the server must choose among the available text/plain representations.
A client that knows that it wants a certain media type, but doesn't understand the different parameterized versions of that type which it is being offered, MAY include all available instances of that type in its Accept header, if it sends an Accept at all, or it MAY just include that media type with no parameters. For example, at URI X, the server may provide
Available-Content-Types: text/html, text/plain;foo=0, text/plain;foo=1
The client may know that it wants text/plain, but may not know what "foo" means. In this case, the client should send either:
Accept: text/plain;foo=0, text/plain;foo=1
or
Accept: text/plain
The header field Put-Accept can be used by the server to indicate that it can handle a PUT of a document of certain type(s) in an analogous manner. In an analogous manner, the server may refuse to recognize PUTs with a Content-Type that does not string-match one of the choices in Put-Accept.
Available-Content-Types and Put-Accept MAY be provided in responses to PUT and POST, also.
This feature depends on the previous feature, "Server-advertised multiple representations of a document".
Some documents have "source" representations which are given by the client, and "processed" representations which are computed by the server based on source representations.
The media type parameters "processed=0" and "processed=1" may be used to augment the media type in the value of the Accept: header or the Available-Content-Types: header.
If a URI makes available some representations which are processed and some which are not, then all items in the Available-Content-Types list SHOULD be parameterized with the "processed" attribute.
By definition, if a client submits a document, it cannot yet have been "processed". Therefore, the Put-Accept header SHOULD NOT contain any "processed" attributes.
If a URI is writable, the server MUST be capable of accepting PUTs to that URI with any type that is advertised with the "processed=0" parameter in Available-Content-Types. For example, if the server advertises:
Available-Content-Types: text/html;processed=1, text/plain;processed=0
then it must be capable of accepting a PUT with Content-Type: text/plain;processed=0.
This does not imply that the server has to accept any PARTICULAR PUT; for example, perhaps the user is unauthorized, the disk is full, or the submitted document has a syntax error (in this last case, error 422 Unprocessable Entity should be returned).
The Recent-Additions-URI header can be provided upon a GET. If provided, it MUST contain a URL which, upon a GET, MUST provide a list, possibly an incomplete list, of recent additions to the set of documents being searched, sorted by date order from most recent to oldest. This is the sort of information found in a blog's feed.
The Recent-Changes-URI header can be provided upon a GET. If provided, it MUST contain a URL which, upon a GET, MUST provide a list, possibly an incomplete list, of recent changes to the set of documents being searched, sorted by date order from most recent to oldest. This is the sort of information found in a wiki's RecentChanges?