Resource Creation

Resource Creation is the Pagelove capability that allows clients to create new resources in the content store using standard HTTP semantics.

A “resource” is typically an HTML document, but may also be any other media type (JSON, images, etc.).

Pagelove supports two distinct creation modes:

• Direct creation via PUT to a known resource name
• Dynamic creation via POST to a template resource

Both modes are governed entirely by AuthorizationRule declarations and standard HTTP behaviour.

Direct resource creation (PUT)

When the client knows the final resource name and can provide the data in full, it can use an HTTP PUT request to supply the server with the new document, using normal HTTP PUT semantics.

Overview

The client performs an HTTP PUT request to the desired resource path:

PUT /new-blog-post.html

The request body contains the full representation of the resource to be created (HTML, JSON, image, etc.).

If the actor has the appropriate authorization to PUT to the provided path, Pagelove saves the supplied document to that path.

Authorization

The server MUST verify that the actor is authorised to perform:

PUT 

using the configured AuthorizationRule set.

If no matching rule permits the operation, the request fails with the appropriate authorization error.

Semantics

• The resource name is client‑defined.
• The content is client‑supplied.
• No templating is performed.
• Standard HTTP semantics apply (ETag, conditional requests, content negotiation, etc.).

Templated resource creation (POST)

Mode 2 is used when the client does not know the final resource name in advance, or when creation must be mediated by server‑side logic.

This mode uses an HTML template resource that dynamically produces the final document.

Overview

1. The client sends an HTTP POST request to a template resource.
2. The template is processed using Pagelove’s templating system.
3. The generated document declares its final storage location using the HTML <base> element.
4. The server verifies that the actor is authorised to create the resource at that final location.
5. The document is written to the content store.
6. The client is redirected to the new resource.

Step 1 – POST to template

The client performs:

POST /templates/new-post.html

The request body, query parameters, and other request metadata are made available to the template execution context.

Step 2 – Template authorization

The server MUST verify that the actor is authorised to perform:

POST 

using AuthorizationRule.

If this check fails, the request is rejected before any templating occurs.

Step 3 – Template processing

The template is processed as an HTML document using Pagelove’s templating system.

The template may incorporate:

• Request body parameters
• Query parameters
• Headers
• Actor identity
• Any other context exposed by the platform

The output of this step is a complete HTML document.

Step 4 – Final resource location via <base>

The generated document MUST contain an HTML <base> element with an href attribute:

<base href="/posts/hello-world.html">

Pagelove interprets this value as the canonical storage location of the newly created resource.

This usage aligns with the standard semantics of the <base> element, which defines the base URL for resolving relative URLs within a document.

Step 5 – Final location authorization

Before writing the generated document to the content store, the server MUST verify that the actor is authorised to perform:

PUT <base.href>

This is a distinct authorization check from the initial POST.

This separation allows:

• Controlled access to creation endpoints
• Independent control over where content may be written

If this check fails, the creation process is aborted and no resource is written.

Step 6 – Resource persistence

If authorization succeeds, the server writes the generated document to the content store at the path specified by base.href.

Standard persistence semantics apply (ETags, indexing, replication, etc.).

Step 7 – Client redirection

Upon successful creation, the server responds with:

301 Moved Permanently

and includes:

Location: <base.href>

This informs the client of the canonical URL of the newly created resource.

Comparison of modes