UserPreferences

PaceSlugHeader3


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 [WWW]definition of "slug" from Wikipedia:

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&#xD3;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&#xD3;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&#xD3;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.

Impacts

Notes


CategoryProposals