Abstract
Adds an HTTP entity-header to be used when creating entries. This header value is a "slug" (i.e. short name identifying the entry) that the server might use when creating an atom:id and/or URI for the entry.
Status
Proposed (Author: ThomasBroyer)
Rationale
See PaceSlugHeader2. The difference here is that Slug is an entity-header, not a request-header, so it can be changed after creation.
Here is the definition of "slug" from Wikipedia:
-
In newspaper editing, a slug is a short name given to an article that is in production. The story is labeled with its slug as it makes its way from the reporter through the editorial process.
Proposal
Add to draft-protocol-09, before section 8.2:
8.2 Slug: Header The value of the Slug entity-header is a "slug", i.e. a short name identifying a resource. Slug = "Slug" ":" *TEXT The syntax of this header MUST conform to the augmented BNF grammar in section 2.1 of the HTTP/1.1 specification [RFC2616]. The TEXT rule is described in section 2.2 of the same document. To include characters outside [ISO88591] in the Slug header, they need to be encoded according to the rules of [RFC2047]. When posting a resource to a collection in order to add a new member, the server might use this information when creating the IRI of the newly-created resource (for instance by using some or all of the words in the last IRI segment). It might eventually also use it when creating the atom:id or as the title of a media link entry (see section 8.5). When sent by a client in subsequent PUT requests to update the member resource, the server MUST NOT change the atom:id of the entry or "media link entry" and SHOULD NOT change the IRI of the resource as well, or SHOULD put a redirection in place, most likely a 301 (Moved Permanently). Servers MAY ignore the Slug entity-header (i.e. not even storing it) or they MAY alter its value in any way before using it; for example, they might filter out some characters or replace accented letters with non-accented ones, spaces with underscores, etc. 8.3 The "app:slug" element The "app:slug" element MAY be used instead of the Slug entity-header when sending an Atom Entry Document over the network (for instance, in POST or PUT requests, or in responses to GET requests). appSlug = element app:slug { text } The "app:slug" element MAY appear as a child of an "atom:entry" or "atom:feed" element. The "app:slug" element, if it does appear in an entry or feed, MUST only appear at most one time. The "app:slug" element is considered foreign markup as defined in Section 6 of [RFC4287]. The content of the "app:slug" element MUST NOT use [RFC2047] encoding. If both the Slug entity-header and the "app:slug" elements are used, then the Slug entity-header value prevails, as found by the W3C TAG in <http://www.w3.org/2001/tag/doc/mime-respect>
Renumber following subsections and update section 8.4 (Example) to use the Slug entity-header and the "app:slug" element:
8.4 Example Below, the client sends a POST request containing an Atom Entry representation to the URI of the Collection: POST /myblog/entries HTTP/1.1 Host: example.org User- Agent: Thingio/1.0 Content- Type: application/atom+xml Content- Length: nnn Slug: =?utf-8?q?Bill=20de=20h=C3=93ra?= <?xml version="1.0" ?> <entry xmlns="http://www.w3.org/2005/Atom"> <title>Bill de hÓra: one of the Atom Publishing Protocol editors</title> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <author><name>John Doe</name></author> <content>Some text.</content> </entry> The server signals a successful creation with a status code of 201. The response includes a "Location" header indicating the URI of the Atom Entry and a representation of that Entry in the body of the response. HTTP/1.1 201 Created Date: Fri, 7 Oct 2005 17:17:11 GMT Content- Length: nnn Content- Type: application/atom+xml; charset="utf-8" Content- Location: http://example.org/edit/bill_de_hora Location: http://example.org/edit/bill_de_hora <?xml version="1.0"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://purl.org/atom/app#"> <title>Bill de hÓra: one of the Atom Publishing Protocol editors</title> <id>tag:example.org,2005-10-07:Bill_de_h%C3%93ra</id> <published>2005-10-07T17:17:11Z</published> <updated>2003-12-13T18:30:02Z</updated> <author><name>John Doe</name></author> <content>Some text.</content> <link rel="edit" href="http://example.org/edit/bill_de_hora"/> <app:slug>Bill de hÓra</app:slug> </entry> Note that the Entry created by the server might not match exactly the Entry POSTed by the client. In particular, a server MAY change the values of various elements in the Entry such as the atom:id, atom:updated and atom:author values and MAY choose to remove or add other elements and attributes, or change element and attribute values. In particular, the publishing system in this example created a new atom:id for the entry, based on the slug, which it stored in an app:slug element, and added an atom:published element.
Note: the example in section 8.6.2 (renumbered from 8.4.2) could be updated to use the "Slug" entity-header as well.