Skip to content

Latest commit

 

History

History
109 lines (84 loc) · 4.11 KB

publish_intents.md

File metadata and controls

109 lines (84 loc) · 4.11 KB
Raw

Publish intents

In order to support the timely publishing of items that are scheduled for publication, it is necessary for the cache control headers to be reduced as the publish time approaches. To allow this to happen, content-store allows publishing apps to register an "intent to publish" for a given content-item.

When serving a content-item, if an upcoming publishing intent exists, content-store will serve the content item with the cache headers reduced accordingly. If no content-item exists for the publish intent, content-store will return a 404, but will still set the cache headers accordingly.

The downstream apps respect content-store's cache headers, so this will be propagated out.

Publish intent format

A publish intent has the following fields:

  • base_path - The path of the item that will be published. Found in the request URL of write requests and the response body for read requests.
  • publish_time - ISO 8601 formatted timestamp. The time the corresponding content item will be published.
  • publishing_app - The publishing app that owns this content (see content_item_fields.md#publishing_app for details)
  • rendering_app - The app that will render this content (see below for details)
  • routes - The routes for this content (see below for details)

For example:

PUT /publish-intent/vat-rates
{
  "publish_time": "2015-01-05T09:00:00+00:00",
  "publishing_app": "publisher",
  "rendering_app": "frontend",
  "routes": [
    {"path": "/vat-rates", "type": "exact"}
  ]
}

Routing for a publish intent

A publish intent requires both a rendering_app and routes in the same way as a content item. See route_registration.md for details of these fields.

When a publish intent is created, content-store will register any routes for it that don't already exist on the corresponding content item (if no content item exists, all the routes will be registered). This is necessary so that incoming requests make it as far as the rendering app, and can therefore have cache headers set as necessary.

Registering an intent to publish

Publishing applications will submit an intent to publish by sending them to the content store. To add or update an intent make a PUT request:

curl https://content-store.publishing.service.gov.uk/publish_intents<base_path> \
  -X PUT \
  -H 'Content-type: application/json' \
  -d '<publish_intent_json>'

where <base_path> is the path on GOV.UK where the content will live (for example /vat-rates) and <publish_intent_json> is the JSON for the publish intent as outlined above.

This will return a 200 or 201 (for update, or create) on success. It will return a 422 along with error details for any validation failures. It will return a 409 if the base_path is already registered to a different publishing_app.

Querying details of a publish intent

Details of a publish intent can be queried by making a GET request:

curl https://content-store.publishing.service.gov.uk/publish_intents<path>

If <path> matches a base_path of a publish intent this will return a 200 along with details of the intent. If it matches a route inside the intent it will return a 303 redirect to the intent at a base path. If no intent matching the <path> is found a 404 will be returned.

Deleting an intent to publish

There's no need to delete publish intents for the normal workflow - publish intents are deleted when the document is published, and any stale publish intents left over are automatically deleted by a nightly housekeeping job.

A publishing application can explicitly delete an intent to publish (for example if an editor cancels a scheduled publishing) by sending a DELETE request:

curl https://content-store.publishing.service.gov.uk/publish_intents<base_path> -X DELETE

This will remove the intent for the corresponding base_path. It will return 200 along with the intent details as JSON on success, or 404 if no matching intent existed.