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.
- 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.
The Publishing API is a Ruby on Rails application that exposes an internal API to publishing applications. It stores its data in a Postgresql database and sends content downstream to the draft and live Content Stores as well as on a Rabbit message queue. Some of the processing of requests is handled asynchronously through Sidekiq which stores jobs in Redis.
The endpoints of the Publishing API are documented in doc/api.md.
Decisions about the design of the Publishing API are recorded as architecture decision records in the doc/arch directory.
Deleting Documents, Editions and Links
To delete content from the Publishing API you will need to create a data migration.
If you need to delete all traces of a document from the system:
require_relative "helpers/delete_content" class RemoveYourDocument < ActiveRecord::Migration # Remove /some/base-path def up Helpers::DeleteContent.destroy_documents_with_links("some-content-id") end end
If you need to delete a single edition:
require_relative "helpers/delete_content" class RemoveYourEdition < ActiveRecord::Migration def up editions = Edition.where(id: 123) Helpers::DeleteContent.destroy_supporting_objects(editions) editions.destroy_all end end
If you need to delete just the links for a document:
require_relative "helpers/delete_content" class RemoveLinks < ActiveRecord::Migration # Remove /some/base-path def up Helpers::DeleteContent.destroy_links("some-content-id") end end
- postgres - the app uses a postgres database
- redis - the Sidekiq worker stores its jobs in Redis
- alphagov/content-store - content is sent to multiple content-stores (draft and live)
These dependencies are set up on the dev vm and if you use bowl to run the app, it will start both the draft and live content store for you. For more information about RabbitMQ, see doc/rabbitmq.md.
Running the application
It downloads and installs dependencies and starts the app on port 3093.
When using GOV.UK virtual machine the app is available at
Running the test suite
You can run the tests locally with:
bundle exec rake.
The publishing API includes contract tests which verify that the service
behaves in the way expected by its clients. We use a library called
pact which follows the consumer driven contract testing pattern.
You can run the pact verification tests on their own using:
$ bundle exec rake pact:verify
See doc/pact_testing.md for more details about the pacts and the pact broker.
Example API requests
curl https://publishing-api.dev.gov.uk/content/<content_id> \ -X PUT \ -H 'Content-type: application/json' \ -d '<content_json>'
Events older then a month are archived to S3, you can import these events back into your local DB by running the rake tasks in lib/tasks/events.rake, after you set up the relevant ENV variables. For example if you want to find all the events that are relevant for a particular content id you can run:
See the rake task for more details.
See admin tasks for more information
See the contributing documentation for more information.