Skip to main content
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 18 Mar 2021

content-data-api: README

Table of Contents

Developers Note

The API work is in progess, and will change alonside the new requirements of the application. As of now, it is only intended for evolving Content Data Admin, but in the long term, once we have an stable version of the API, will be shareble across GOV.UK.

Backwards incompatable changes

Currently the API is in alpha, so users should expect backwards incompatable changes without warning.

When the API is live, we will follow the GDS API technical and data standards

  • make backwards compatible changes where possible
  • use a version number as part of the URL when making backwards incompatible changes
  • make a new endpoint available for significant changes
  • provide notices for deprecated endpoints

This is a middleman powered microsite for the API documentation. It it is hosted by Github Pages and will eventually be available at https://content-data-api.publishing.service.gov.uk.

This documentation is built from source files in this repository and an OpenAPI specification file, which is used to generate the reference section.

The framework for this documentation is provided by the GOV.UK Tech Docs Template and through the use of a fork of widdershins to convert the openapi.yaml to Markdown.

Updating content

You can suggest edits by making changes in a branch or fork of this project and then opening a pull request.

The reference.html page is built using the openapi.yaml file.

OpenAPI is similar to JSON schema. It describes the requests and responses for each endpoint, so we should update it any time we change the API itself.

For more information, see the OpenAPI specification on github.

Some aspects of the reference.html page are controlled by templates which are stored in the /templates of this repository.

Other HTML pages are in the /source of this repository and are authored using Markdown.

Updating the template

You can update to the latest version of tech-docs-template by running:

bundle update govuk_tech_docs

Read the changelog for the gem for the latest changes.

Running documentation locally

All commands should be run from docs/api.

Preview changes

Whilst writing documentation we can run a middleman server to preview how the published version will look in the browser. After saving a change the preview in the browser will automatically refresh on HTML pages. However for changes to openapi.yaml you will need to restart the preview.

The preview is only available on our own computer. Others won't be able to access it if they are given the link.

Type the following to start the server:

make server API_SPEC=../../openapi.yaml

You should now be able to view a live preview at http://localhost:4567.

Publishing changes

You can deploy with the following command:

make publish API_SPEC=../../openapi.yaml

This will push to the gh-pages branch and therefore deploy to GitHub Pages.

License

MIT License