Skip to main content

Application: publishing-api

API to publish content on GOV.UK


The Publishing API aims to provide workflow as a service so that common publishing features can be written once and used by all publishing applications across Government. Content can be stored and retrieved using the API and workflow actions can be performed, such as creating a new draft or publishing an existing piece of content.

Publishing API sends content downstream to the draft and live Content Stores, as well as on a Rabbit message queue, which enables things like sending emails to users subscribed to that content. Read “Downstream Sidekiq background processing triggered by publishing”.


  • Document: A document is a piece of content in a particular locale. It is associated with editions that represent the versions of the document.
  • Edition: The content of a document is represented by an edition, it represents a distinct version of a Document.
  • Content Item: A representation of content that can be sent to a content store.
  • Links: Used to capture relationships between pieces of content (e.g. parent/child). Can be of type link set link or edition link.
  • Unpublishing: An object indicating a previously published edition which has been removed from the live site.
  • User: A user of the system, which is used to track who initiated requests and to restrict access to draft content.
  • Path Reservation: An object that attributes a path on GOV.UK to a piece of content. It is used when paths need to be reserved before that content enters the system.
  • Event Log: A log of all requests to the Publishing API that have the potential to mutate its internal state.
  • Action: A record of activity on a particular edition, used to assist custom workflows of publishing applications.
  • Link Expansion: A process that converts the stored and automatic links for an edition into a JSON representation.
  • Dependency Resolution: A process that determines other editions that require updating downstream as a result of a change to an edition.

Technical documentation

This is a Ruby on Rails app, and should follow our Rails app conventions.

You can use the GOV.UK Docker environment to run the application and its tests with all the necessary dependencies. Follow the usage instructions to get started.

Use GOV.UK Docker to run any commands that follow.

Running the test suite

You can run the tests locally with: bundle exec rake.

The Publishing API also has contract tests with GDS API Adapters (where it acts as the “provider”) and with Content Store ( where it acts as the contract “consumer”). Read the guidance for how to run the tests locally.

Further documentation


MIT License