The Atom Publishing Protocol
updated by
- rfc-8996 — Deprecating TLS 1.0 and TLS 1.1
Extracted elements (30)
AtomPub gives servers wide latitude in processing client requests. Servers can accept, reject, delay, moderate, censor, reformat, translate, relocate, or re-categorize submitted content, and clients must be written flexibly to accept whatever the server decides are the results of its submissions.
The 'type' parameter was added to application/atom+xml because implementation experience demonstrated that Atom Feed and Entry Documents have different processing models and need to be differentiated without examining document content. Producers of Entry Documents SHOULD use the parameter regardless of whether it is required.
Deletion of a Media Link Entry via DELETE SHOULD result in the deletion of the corresponding Media Resource. Clients and servers should treat the Media Link Entry and its associated Media Resource as a coupled pair for deletion purposes.
Client and server implementations MUST be capable of being configured to use HTTP Basic Authentication (RFC 2617) in conjunction with TLS 1.0 or a subsequent standards-track version of TLS, following the conventions for HTTP over TLS in RFC 2818.
Clients MUST NOT assume that an Atom Entry returned in a Collection Feed is a full representation of an Entry Resource, and SHOULD perform a GET on the Member Entry URI before editing it.
Collection Resources MUST provide representations as Atom Feed Documents whose Entries contain the IRIs of Members. Entries in the returned Feed SHOULD be ordered by app:edited with the most recently edited Entries first.
If a POST creation response contains a Content-Location header that matches the Location header character-for-character, the client is authorized to treat the response entity as a complete representation of the new Entry. Without a matching Content-Location header, the client MUST NOT assume the returned entity is complete.
If the app:draft element is absent from app:control, servers that support the extension MUST behave as though an app:draft element containing 'no' was sent, meaning the Resource is to be made publicly visible.
Processors encountering unrecognized foreign markup in an AtomPub document MUST NOT stop processing and MUST NOT signal an error. Clients SHOULD preserve foreign markup when transmitting Category or Service Documents.
The app:service element MUST contain one or more app:workspace elements. Each app:workspace MUST contain one atom:title element. Each app:collection element MUST contain an 'href' attribute giving the Collection IRI and MUST contain one atom:title element.
To avoid unintentional data loss when editing Member or Media Link Entries via PUT, an AtomPub client SHOULD preserve all metadata not intentionally modified, including unknown foreign markup.
When a Member Resource is successfully created via POST, the server MUST return a 201 status code and MUST include the Member Entry URI in a Location header. The server SHOULD also return a response body containing the Atom Entry Document representing the newly created Resource.
When a server accepts a POST of a non-Atom Media Resource, it MUST create two new Resources: the Media Resource corresponding to the POSTed entity, and an associated Media Link Entry. Successful responses MUST include the URI of the Media Link Entry in the Location header.
When a server returns a partial list of a Collection, the first partial list MUST contain the most recently edited Member Resources and MUST include an atom:link with rel='next' pointing to the URI of the next partial list.
When no app:accept element is present in an app:collection, clients SHOULD treat this as equivalent to an app:accept element containing 'application/atom+xml;type=entry'. If one app:accept element exists and is empty, clients SHOULD assume the Collection does not support creating new Entries.
A Category Document (media type application/atomcat+xml) contains lists of categories using atom:category elements. The app:categories element may carry a 'fixed' attribute ('yes'/'no') indicating whether the category set is closed, and an optional 'scheme' attribute inherited by child categories lacking their own scheme.
A Media Link Entry is an Atom Entry that describes a Media Resource. It MUST have an atom:content element with a 'src' attribute whose value is an IRI for the Media Resource, and SHOULD contain an atom:link with rel='edit-media' pointing to the IRI for modifying the Media Resource.
A Service Document (media type application/atomsvc+xml) groups available Collections into Workspaces and is used by clients to discover Collection IRIs, accepted media types, and available categories before authoring begins. The document's root element is app:service under the namespace http://www.w3.org/2007/app.
AtomPub defines a 'type' parameter for the application/atom+xml media type with values 'entry' or 'feed', distinguishing Atom Entry Documents (root element MUST be atom:entry) from Atom Feed Documents (root element MUST be atom:feed). Processors that do not recognize the parameter MUST ignore it and examine the root element.
The app:control element (namespace http://www.w3.org/2007/app) is a structured extension that MAY appear as a child of atom:entry to carry publishing control metadata. It MUST appear at most once per Entry and contains an optional app:draft child element with value 'yes' or 'no'.
The app:edited element is a Date construct (per RFC 4287) indicating the last time an Entry was edited or, if never edited, when it was created. Collection Feed Entries SHOULD contain exactly one app:edited element; MUST NOT contain more than one.
The 'edit' link relation (added to the Atom Registry of Link Relations) specifies that the href IRI is the URI of an editable Member Entry, usable for GET, PUT, and DELETE. An atom:entry MUST NOT contain more than one 'edit' link relation.
The 'edit-media' link relation specifies an IRI that can be used to modify the Media Resource associated with an atom:entry. An entry MAY contain zero or more edit-media links, but MUST NOT contain more than one with the same 'type' and 'hreflang' attribute values; all edit-media links in the same entry reference the same Resource.
The Slug HTTP entity-header allows a client to suggest a string for use in constructing the URI of a newly created Resource. Servers MAY use, alter, or ignore the value. The field value is the percent-encoded UTF-8 encoding of the desired character sequence.
RFC 5023 registers three new IANA entries: the media type application/atomcat+xml (file extension .atomcat) for Category Documents, the media type application/atomsvc+xml (file extension .atomsvc) for Service Documents, and the SLUG HTTP header field. It also registers the 'edit' and 'edit-media' link relations in the Atom Registry of Link Relations and adds a reference in the application/atom+xml registration for the new 'type' parameter.
AtomPub does not define a means of detecting duplicate requests; accidentally sent duplicate requests are indistinguishable from intentional replay attacks. Implementations are susceptible to replay attacks.
AtomPub server implementations need to take adequate precautions against denial-of-service attacks that could cause malicious clients to consume excessive CPU, memory, or disk resources.
Because servers are allowed to modify Entry content before publishing, XML digital signatures applied by clients are only reliable to the receiving server. A server that changes a signed Entry SHOULD strip the client's signature before publishing to prevent third parties from attempting to validate an invalid signature.
Server implementations are strongly encouraged to verify that client-supplied content is safe before accepting, processing, or publishing it to guard against code injection and cross-site scripting. For HTML, a whitelist of acceptable content is more effective than a blacklist.
The Slug header field syntax is: Slug = 'Slug' ':' *slugtext, where slugtext = %x20-7E | LWS. The value is the percent-encoded UTF-8 encoding of the client's desired string; octets outside %20-24 and %26-7E must be percent-encoded.