POST method
The HTTP POST method appends content to a document fragment or creates a new resource. When combined with a selector range unit, it appends the request body as a child of the matched element.
When to reach for it
Use POST to add content without replacing what already exists. The server returns 206 Partial Content with a Content-Range header identifying the updated element.
All POST requests are subject to authorization.
Examples
Append to a list
Given a document with a list, append a new item:
POST /post-append-test.html
Range: selector=ul
Content-Type: text/html
<li>New item</li>
HTTP/1.1 206
<li>New item</li>
Verify the append
Reading the list back confirms that existing items are preserved alongside the new one:
GET /post-verify-test.html
Range: selector=ul
HTTP/1.1 206
<ul>
<li>Existing item</li>
<li>Appended item</li>
</ul>
What the response contains
The response body is the markup you created, without any whitespace before or after it. So if your request body ends in a newline, the response does not. The ETag describes exactly that body: hash the body with SHA-256 and you get the first part of the ETag. A later read of the created element returns the same ETag. The stored document keeps the whitespace you sent.
A body that is only whitespace creates no element, so it is refused with 422 Unprocessable Entity and an error in HTML Microdata. Nothing is stored and the response has no ETag. A POST to a transient element is refused the same way.
POST with no selector
A POST with no Range: selector= works in one of two ways, depending on the page it is sent to.
- If the page is a template, the server builds a page from your form data and stores it at the template's
<base href>. See Resource creation. A template with no<base href>is refused with422 Unprocessable Entity. - If the page does not exist, or exists and is not a template, the server saves your body as the whole page. This is a success: you get the database's answer, and the page holds your body. It is not an error, and you do not need a
<base href>.
Where an element deny applies to you, a POST with no selector is checked like a whole-page PUT of its body. See an element deny also guards a whole-page write.
Placement
By default POST appends the request body as the last child of the element matched by Range:. To insert at a different position, supply placement=<value> as a Range: sub-field:
| Placement | Insertion site |
|---|---|
append (default) |
Last child of the matched element |
prepend |
First child of the matched element |
before |
Previous sibling of the matched element |
after |
Next sibling of the matched element |
Put placement=<keyword> after the selector and write nothing else after the ;: Range: selector=ul; placement=prepend. Write placement in lower case, with no space before the =. The keyword can be in any case. If anything else comes before the placement or after the keyword, including a second placement=, the server ignores the placement and appends the body to the element.
placement=before and placement=after against a parentless anchor (e.g. <html>) return 400 Bad Request — there's no sibling slot.
Prepend a list item
POST /post-prepend-test.html
Range: selector=ul; placement=prepend
Content-Type: text/html
<li>New first item</li>
HTTP/1.1 206
<li>New first item</li>
Insert before a specific sibling
POST /post-before-test.html
Range: selector=li#beta; placement=before
Content-Type: text/html
<li>Inserted before beta</li>
HTTP/1.1 206
<li>Inserted before beta</li>
Insert after a specific sibling
POST /post-after-test.html
Range: selector=li#alpha; placement=after
Content-Type: text/html
<li>Inserted after alpha</li>
HTTP/1.1 206
<li>Inserted after alpha</li>
Posting to a large page
A POST addressed by #id, by .class, by an exact attribute value such as [data-key="7"], or by a position inside one of those, such as #column-4 .cards > article:first-child, can read only the part of the page it changes, so its cost does not grow with the page. The server reads the part of the page around the new element, adds the element there, and stores only that part.
When anything else needs the whole page, the POST reads the whole page as before. That happens when the request has an If-None-Match header, when a shape constraint applies to the page or the page declares one, when a transition rule watches something on the page or in your body, when your schema has a @validate expression or a @write resolver, and when the page uses itemref or declares a namespace. The response does not say which route was taken, but two things differ afterwards. The live-update event for the POST has an empty etag, and a WebDAV PROPFIND with Depth: 1 leaves the page out of the <D:getetag> values until the page has been read whole again. A POST over WebDAV always reads the whole page and answers as it always has, with the page's ETag.
The response is the same either way. It carries the created element and the element's ETag, which a GET of the element returns next. A POST that reads only its part of the page does not work out the page's own ETag. The live-update event it sends names none, and the next GET of the page returns the new one. You can send an If-Match or If-None-Match for the page straight after a POST, before any GET, and it is compared with the page's real ETag.
Error cases
| Condition | Status |
|---|---|
| Document does not exist | 404 Not Found |
| Selector matches no element | 416 Range Not Satisfiable |
| Authorization denied | 403 Forbidden |
A Range header with more than one selector= |
400 Bad Request |
| Schema validation fails | 422 Unprocessable Entity |
| Shape or cardinality rule broken, including by an append re-applied after a concurrent write | 422 Unprocessable Entity |
| Concurrent writes kept the append from landing after 16 attempts | 409 Conflict |
| Host has transition rules and the page changed while the write was being checked | 409 Conflict |
| Host has transition rules and a file that is not HTML would replace a page holding a watched item with no declared exit | 422 Unprocessable Entity |
Absence and denial are distinct. A selector that matches no element gets
416, and one you are not permitted to write gets401/403— the two are never confused. Where the edge cannot see your target it re-checks against the live document before answering, so a416means the element really was absent at that moment — for an append that does not name a placement. APOSTthat specifiesplacement=beforeorplacement=aftercurrently refuses instead of reporting416when its anchor is absent.Two further cases refuse rather than reporting
416: a target that exists but is covered by a rule denying it, which is a genuine authorization answer rather than an absence; and a target you would not be permitted to read, since "there is nothing there" is itself information about the page. If you can write to part of a page you cannot read, writes refuse identically whether the target exists or not.
Concurrency
A selector POST is additive: it appends to the matched element rather than replacing it. Two clients that append to the same element at the same time normally both land, and neither append is lost. The server applies each append against the latest stored version of the document, so concurrent appends accumulate rather than one overwriting the other.
The server checks an append again when it re-applies it. If the two appends
together break a shape constraint or a schema cardinality rule, the later one
gets 422 Unprocessable Entity and nothing is saved. If concurrent writes
keep changing the page and the append still has not landed after 16 attempts,
you get 409 Conflict with a WriteContention error. The same happens if a
concurrent write turns the page into a template, or a template into a page,
while the append is being retried. Inspect the actual refusal and current target before deciding on another request; a 409 alone does not establish that repeating the append is appropriate.
On a host with transition rules, the server does not retry an append for you. Every POST the rules check is pinned to the version of the page the server read, and if the page changed in between, you get 409 Conflict with a WriteContention error on the first clash. Review the current target and intended addition before preparing a deliberate new request; the new attempt is evaluated against that current state. See TransitionConstraint for the writes the rules do not check.
A POST of a file that is not HTML, with no selector, to a path that holds a web page counts as deleting that page when the host has transition rules. It is refused with 422 if the page holds a watched item and the rules declare no exit for it. See Transition constraints. A POST with a selector never saves a file. Sent to a path that names a page, it adds its body to the element as markup, whatever its Content-Type. Sent to a directory path, it updates every matching page, and a text/plain body there sets the text of each matched element.
If you send a conditional append with If-Match: "<etag>" and the document
changed since that ETag, the append is rejected with 412 Precondition Failed
rather than applied against the new state. Retain the submitted body and review
the current target before preparing a new conditional request.
Keep the frozen submitted body, intended resource/selector and original validator separate from any newer local draft until the outcome is resolved. If the reply is lost, treat the outcome as Unknown, not a confirmed refusal: an append may already have committed, and repeating it can add the same content again. Inspect current state through a permitted read and use operation-specific evidence where the application provides it before deciding on another request. Matching content alone does not identify which request inserted it. Reconcile independently persisted trigger effects separately; do not assume automatic deduplication. See Save a fragment without losing your draft for the pending/draft distinction; its PUT example is not an append-retry implementation.
A selector-scoped If-Match can also fail for a second reason. If the version
you quoted is still current but the ETag does not name the element as it is
stored, the 412 body carries a problem item of type
https://pagelove.org/Problem/RepresentationMismatch. Re-reading will not
help. See PUT for the full
explanation, including which pages can and cannot be written back through.
The same eligible internal re-apply applies when the matched element was projected from another resource via
<p:stamp>or<p:include>: the append is routed to that element's origin resource. It remains subject to the same conditional and transition guards, validation and retry limits; routing to an origin does not make every concurrent append succeed or make client replay duplicate-safe.
See also
- Resource Creation — create new resources via POST to templates
- Modeling data — schema validators that check content values on write