Publishing API

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".

Nomenclature

• 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.

Linting

Like all GOV.UK's Rails apps, we use rubocop for linting Ruby.

We also have SQL linting using SQLFluff. You can install this locally with brew install sqlfluff. Use sqlfluff lint to check the SQL passes the rules, or sqlfluff fix to automatically fix any issues that can be.

Profiling and Benchmarks

In development mode, you can use rack-mini-profiler to get performance information (such as flamegraphs). There's full documentation in the gem's readme, but often it's as simple as appending

pp=flamegraph

to the query string.

There is also a suite of benchmarks, written with RSpec. These require a full database (e.g. a dump of integration), and are intended to be run manually on a developer's workstation. Run them with:

bundle exec rspec --options .rspec.benchmark

The benchmarks will output various statistics to the console, as well as:

• timings for all SQL queries and govspeak renders in tmp/benchmarks/instrumentation
• StackProf profiles (which can be viewed using https://speedscope.app) in tmp/benchmarks/profiles
• SQL query plans for any queries slower than the threshold set in the benchmarks in tmp/benchmarks/sql

Further documentation

• Publishing API's API
• Architecture decision records
• Admin tasks
• Deleting Documents, Editions and Links
• Writing data migrations

Licence

MIT License