Creator websites

Change a website page

Rewrites the document, the metadata or the address of one page. Needs content: write, and is a write.

Send at least one of path, html and meta. An omitted property is left alone; html replaces the whole document, because a page is one document and there is nothing in it Commune understands well enough to patch.

kind and status are not here. The kind decides whether path is a path or a pattern, so changing it would make a valid page invalid in one statement; the state has two operations of its own, so that an edit to your text cannot put a page live by accident.

If the page is published the change is live immediately. Changing an article pattern keeps the old URLs working: a request to one of them is redirected to the article's new address.

Publishes no event.

patch/website-pages/{page}

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/website-pages/{page}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: content:write)

Headers

Idempotency-Keystring required

A value of your choosing naming the change this request is making.

Send the same value again to retry the same request. Commune replays the answer the first attempt gave instead of making the change twice, and marks the replay with an Idempotent-Replay: true response header. Send a different value for a different change: a key reused for a request that differs in any way answers 409, because replaying an answer to a question you did not ask is a wrong answer you could not detect.

A UUID per change is the usual choice. Remembered for 24 hours, per credential, so two credentials choosing the same value never see each other's answers.

Required, not optional.

Request body

pathstring

The page's new address, under the same rules as on create.

htmlstring

The whole document, replacing what was there. There is no partial edit of a page: a page is one document, and nothing in it is structured enough for Commune to patch.

metaobject

The metadata to inject, replacing what was there.

Response

The page as it stands after the change.

object'site_page' required

Always site_page.

idstring uuid required

Stable identifier.

kind'page' | 'newsletter' | 'article' required

What a website page is for, which also decides what its path means.

page is a fixed path and anything the creator wants. newsletter is the article list, at most one per newsletter, and its path is where Commune points the newsletter's name and avatar. article is a URL pattern containing :article that renders every article, so its path is a pattern rather than an address.

pathstring required

Where the page answers: an absolute path for a page or a newsletter page, and a URL pattern for an article one.

status'draft' | 'published' required

Whether a page has a public address. A draft is reachable only through its signed preview_url; an edit to a published page is live on commit, because a creator website has no deploy step.

blockedboolean required

Whether Commune has taken this page down. A blocked page answers a refusal to visitors, stays out of the sitemap, keeps its address reserved so nothing else can claim it, and cannot be changed or deleted through this API.

metaobject required

Metadata Commune injects into the page's <head> when it serves it: a title, a description, a social image.

byte_sizeinteger required

How large the document is, in bytes rather than characters, against a limit of 2097152.

urlstring uri nullable required

Where the page is served, or null. Null for a draft, for a page Commune has taken down, for an article page, which is a pattern rather than one address, and for a newsletter whose website hostname is not live yet.

preview_urlstring uri nullable required

A signed link that opens this one draft, or null. It names this page and this newsletter, expires after a week, and opens nothing else. Null for a published page and when Commune holds no signing key on this deployment.

published_atstring date-time nullable

When the page first went live. It records the first publication rather than the current state, so unpublishing deliberately leaves it.

created_atstring date-time required

When the page was written.

updated_atstring date-time required

When it last changed.

htmlstring required

The whole document, with its CSS and JavaScript inline or linked. At most 2097152 bytes.

Example response

{
  "newsletter": {
    "object": "newsletter",
    "id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
  },
  "path": "/about"
}

Changes

No recorded changes to this operation across all 1 revision of this API.