Skip to content

Commit 7ffa1fb

Browse files
mxco86mxco86
committed
Merge remote-tracking branch 'hmpps-integration-api-docs/main' into merge-tech-docs
2 parents 10a77e1 + 039c27f commit 7ffa1fb

22 files changed

+438
-1
lines changed

‎.github/dependabot.yml

+11
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,17 @@ updates:
1111
- "patch"
1212
patterns:
1313
- "*"
14+
- package-ecosystem: "bundler"
15+
directory: "/tech-docs"
16+
schedule:
17+
interval: "weekly"
18+
groups:
19+
minor:
20+
update-types:
21+
- "minor"
22+
- "patch"
23+
patterns:
24+
- "*"
1425

1526
- package-ecosystem: "github-actions"
1627
directory: "/"

‎.github/workflows/format-code.yml

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: Format code
2+
3+
on:
4+
pull_request:
5+
types: [opened, edited, reopened, synchronize]
6+
7+
jobs:
8+
format-code:
9+
name: 🧹 Format code
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout
13+
uses: actions/checkout@v4
14+
- name: Format code
15+
uses: ministryofjustice/github-actions/code-formatter@v14
16+
env:
17+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/publish.yml

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Publish gh-pages
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
paths-ignore:
7+
- "docs/**"
8+
9+
# GITHUB_TOKEN permissions to allow deployment to GitHub Pages
10+
permissions:
11+
contents: read
12+
pages: write
13+
id-token: write
14+
15+
# Allow one concurrent deployment
16+
concurrency:
17+
group: "pages"
18+
cancel-in-progress: true
19+
20+
jobs:
21+
build:
22+
name: 🏗 Build application
23+
runs-on: ubuntu-latest
24+
container:
25+
image: ministryofjustice/tech-docs-github-pages-publisher:v3.0.1
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v4
29+
- name: Compile Markdown to HTML and create artifact
30+
run: |
31+
/scripts/deploy.sh
32+
working-directory: tech-docs/
33+
- name: Upload artifact to be published
34+
uses: actions/upload-artifact@v4
35+
with:
36+
name: github-pages
37+
path: artifact.tar
38+
retention-days: 1
39+
40+
deploy:
41+
name: 🚀 Deploy application
42+
needs: build
43+
if: github.ref_name == 'main'
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
runs-on: ubuntu-latest
48+
steps:
49+
- name: Setup Pages
50+
uses: actions/configure-pages@v5
51+
- name: Deploy to GitHub Pages
52+
id: deployment
53+
uses: actions/deploy-pages@v4

‎.github/workflows/review-dependency-changes.yml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Need a GitHub Advanced Security license to run this action on private repos.
2+
3+
name: Review dependency changes
4+
on:
5+
pull_request:
6+
types: [opened, edited, reopened, synchronize]
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
review-dependency-changes:
13+
name: 🕵️ Review dependency changes
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout Repository
17+
uses: actions/checkout@v4
18+
- name: Review dependency changes
19+
uses: actions/dependency-review-action@v4
20+
with:
21+
# Possible values: critical, high, moderate, low
22+
fail-on-severity: critical

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -89,3 +89,6 @@ __pycache__/
8989

9090
# Localstack
9191
localstack/cache
92+
93+
.env
94+
.idea

‎Makefile

+22-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
IMAGE := ministryofjustice/tech-docs-github-pages-publisher:v3
2+
13
authenticate-docker:
24
./scripts/authenticate_docker.sh
35

@@ -49,4 +51,23 @@ check:
4951
generate-client-certificate:
5052
cd ./scripts/client_certificates && ./generate.sh
5153

52-
.PHONY: authenticate-docker build-dev test serve publish unit-test smoke-test build lint
54+
preview-docs:
55+
docker run --rm \
56+
-v $$(pwd)/config:/app/config \
57+
-v $$(pwd)/source:/app/source \
58+
-p 4567:4567 \
59+
-it $(IMAGE) /scripts/preview.sh
60+
61+
deploy-docs:
62+
docker run --rm \
63+
-v $$(pwd)/config:/app/config \
64+
-v $$(pwd)/source:/app/source \
65+
-it $(IMAGE) /scripts/deploy.sh
66+
67+
check-docs:
68+
docker run --rm \
69+
-v $$(pwd)/config:/app/config \
70+
-v $$(pwd)/source:/app/source \
71+
-it $(IMAGE) /scripts/check-url-links.sh
72+
73+
.PHONY: authenticate-docker build-dev test serve publish unit-test smoke-test build lint preview-docs check-docs

‎docs/.gitkeep

Whitespace-only changes.

‎tech-docs/Gemfile

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
source "https://rubygems.org"
2+
ruby "3.1.0"

‎tech-docs/Gemfile.lock

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
GEM
2+
remote: https://rubygems.org/
3+
specs:
4+
5+
PLATFORMS
6+
arm64-darwin-21
7+
x64-mingw32
8+
x86_64-darwin-20
9+
x86_64-linux
10+
11+
DEPENDENCIES
12+
13+
RUBY VERSION
14+
ruby 3.1.0
15+
16+
BUNDLED WITH
17+
2.4.5

‎tech-docs/README.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# HMPPS Integration API Documentation Site
2+
3+
[![repo standards badge](https://img.shields.io/badge/dynamic/json?color=blue&style=flat&logo=github&label=MoJ%20Compliant&query=%24.result&url=https%3A%2F%2Foperations-engineering-reports.cloud-platform.service.justice.gov.uk%2Fapi%2Fv1%2Fcompliant_public_repositories%2Ftemplate-documentation-site)](https://operations-engineering-reports.cloud-platform.service.justice.gov.uk/public-github-repositories.html#template-documentation-site "Link to report")
4+
5+
## Contents
6+
7+
- [About this project](#about-this-project)
8+
- [Getting started](#getting-started)
9+
- [Prerequisites](#prerequisites)
10+
- [Installation](#installation)
11+
- [Usage](#usage)
12+
- [Running the application](#running-the-application)
13+
- [Running checks](#running-checks)
14+
- [Updating configuration](#updating-configuration)
15+
- [Publishing](#publishing)
16+
17+
## About this project
18+
19+
This repository is used to generate the [technical documentation website](https://ministryofjustice.github.io/hmpps-integration-api-docs) for the [HMPPS Integration API](https://github.com/ministryofjustice/hmpps-integration-api).
20+
21+
## Getting started
22+
23+
### Prerequisites
24+
25+
- [Docker](https://www.docker.com/get-started/)
26+
- [Ruby](https://github.com/rbenv/rbenv)
27+
28+
### Installation
29+
30+
1. Clone the repository.
31+
32+
```bash
33+
git clone git@github.com:ministryofjustice/hmpps-integration-api-docs.git
34+
```
35+
36+
## Usage
37+
38+
### Running the application
39+
40+
To run the application for local development:
41+
42+
```bash
43+
make preview
44+
```
45+
46+
Then visit http://localhost:4567.
47+
48+
### Running checks
49+
50+
To check the application compiles and URLs are valid:
51+
52+
```bash
53+
make check
54+
```
55+
56+
For more details see the [Tech Docs GitHub Pages Publisher GitHub repository](https://github.com/ministryofjustice/tech-docs-github-pages-publisher).
57+
58+
### Updating configuration
59+
60+
Aspects of the documentation site such as the header and sidebar can be configured using [config/tech-docs.yml](config/tech-docs.yml). Further configuration options are described on the [Tech Docs Template website: Global Configuration](https://tdt-documentation.london.cloudapps.digital/configure_project/global_configuration/).
61+
62+
## Publishing
63+
64+
Changes pushed or merged into to `main` are automatically published to GitHub Pages and viewable at https://ministryofjustice.github.io/hmpps-integration-api-docs.
65+
66+
## Reviewing
67+
68+
Should you need to review the content of our documentation, ensure that the `review_in` field is updated as part of the front matter of the markdown page. This should be formatted `yyyy-mm-dd`.
69+
70+
A Ministry of Justice tool named [Tech Docs Monitor _also known as_ Daniel the Manual Spaniel](https://github.com/ministryofjustice/tech-docs-monitor) will send a notification to the Slack channel specified in the `owner_slack` property when a document is due for review.

‎tech-docs/config/tech-docs.yml

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# See the available options: https://tdt-documentation.london.cloudapps.digital/configure_project/global_configuration/#configure-your-documentation-site
2+
3+
# Host to use for canonical URL generation (without trailing slash)
4+
host: https://ministryofjustice.github.io/hmpps-integration-api-docs
5+
6+
# Header-related options
7+
show_govuk_logo: false
8+
service_name: HMPPS Integration API And Events Documentation
9+
service_link: /
10+
11+
# Links to show on right-hand-side of header
12+
header_links:
13+
Docs GitHub: https://github.com/ministryofjustice/hmpps-integration-api-docs
14+
Integration API GitHub: https://github.com/ministryofjustice/hmpps-integration-api
15+
Integration Events Github: https://github.com/ministryofjustice/hmpps-integration-events
16+
17+
# Enables search functionality. This indexes pages only and is not recommended for single-page sites.
18+
enable_search: true
19+
20+
# Tracking ID from Google Analytics (e.g. UA-XXXX-Y)
21+
ga_tracking_id:
22+
23+
# Enable collapsible navigation in the sidebar
24+
collapsible_nav: true
25+
26+
multipage_nav: true
27+
28+
# Table of contents depth – how many levels to include in the table of contents.
29+
# If your ToC is too long, reduce this number and we'll only show higher-level
30+
# headings.
31+
max_toc_heading_level: 2
32+
33+
# Prevent robots from indexing (e.g. whilst in development)
34+
prevent_indexing: true
35+
36+
show_contribution_banner: true
37+
github_repo: ministryofjustice/hmpps-integration-api-docs
38+
github_branch: main
39+
40+
api_path: https://ministryofjustice.github.io/hmpps-integration-api/openapi/api-docs.json

‎tech-docs/source/api-changes-and-versioning.html.md.erb

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: API Changes and Versioning
3+
weight: 4
4+
owner_slack: "#hmpps-integration-api-alerts"
5+
last_reviewed_on: 2024-09-03
6+
review_in: 3 months
7+
---
8+
9+
# API Changes and Versioning
10+
11+
As HMPPS Integration API evolves, more features will be added, and features that already exist will change. Both consumers and MOJ must be prepared to handle these changes, and to manage them carefully.
12+
13+
There will broadly speaking be two kinds of changes - "non-breaking" changes, where consumers should be able to use the new version without modifying their usage, and "breaking" changes where we would expect that consumers would not be able to seamlessly use the new version.
14+
15+
## Non-Breaking Change
16+
17+
We would like to minimise the number of breaking changes, and where this is not possible, we will increment the API version and manage the migration.
18+
19+
- MOJ - must not change or remove an existing data element unless we are certain it is not in use
20+
- MOJ - must update documentation to reflect any changes
21+
- MOJ - may add new elements and change/remove elements that we know are not in use
22+
- Consumers - implementation must accept new elements and changes to elements that are not in use (i.e. it must be resilient to non-breaking API changes)
23+
24+
## Breaking Change
25+
26+
Where a non-breaking change is not possible, there is then a breaking change. In this case, we will increment the version of the API
27+
28+
- MOJ - must update documentation, and explicitly call out the change between versions
29+
- MOJ - must distribute the new documentation as soon as practical
30+
- MOJ - must run both versions of the API, as long as this is practical, for at least 1 month
31+
- Consumers - must commit to moving to the new version of the API within a reasonable timescale, usually 1 month
32+
- Depending on the size of the change, MOJ may require the Consumer to go through additional re-assurance steps
33+
34+
## Ongoing Assurance
35+
36+
As part of including new functionality into the system, new processes will be available to be undertaken via the API. As these are introduced, we will ask consumers to go through further rounds of assurance, broadly similar to the initial round described above.
37+
38+
## URI Path
39+
40+
Where versioning must be implemented, it will be in the form of a path parameter:
41+
42+
```
43+
https://integration-api.hmpps.service.justice.gov.uk/v1/images/123456
44+
```
45+
46+
Versions will increment by major version only and no minor version updates will be supported.

‎tech-docs/source/authentication.html.md.erb

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Authentication
3+
weight: 3
4+
owner_slack: "#hmpps-integration-api-alerts"
5+
last_reviewed_on: 2024-09-03
6+
review_in: 3 months
7+
---
8+
9+
# Authentication
10+
11+
## Reading from the API
12+
13+
API consumers are authenticated on a service to service level using:
14+
15+
- [Mutual TLS](https://www.cloudflare.com/en-gb/learning/access-management/what-is-mutual-tls/) to ensure trust on both the server and client side
16+
- API keys to track and manage usage of the client
17+
18+
Using mutual TLS authentication allows HMPPS to additionally verify the identity of a consumer before securely providing any data and therefore a client must present it's own TLS certificate, issued by HMPPS, as part of making a request. Providing an API key enables per-client management of API interactions such as rate limiting and therefore a valid API key must also be presented as part of making a request.
19+
20+
Providing a client certificate and key for mTLS is dependent on the tools used to make the request. As an example when using `curl` the certificate and key are provided as request parameters. If a valid TLS certificate and private key is not supplied the TLS handshake will not complete.
21+
22+
Providing an API key can be done using an HTTP header called `x-api-key` with the value of the API key as the header value, ensuring it's not encoded in Base64. If a valid API key is not supplied a `403 Forbidden` HTTP response is returned.
23+
24+
### Example: Read from an API Endpoint
25+
26+
To make an authenticated data request to the API using the client-specific TLS certificate, private key and API key:
27+
28+
```sh
29+
curl --cert <client-cert-file> --key <client-key-file> -X GET https://<environment>.integration-api.hmpps.service.justice.gov.uk/v1/persons/X802678/risks/scores -H 'x-api-key: <api-key>'
30+
```
31+
32+
## Interacting with an HMPPS SQS Queue
33+
34+
For consumers that have an SQS queue configured, temporary AWS access credentials that can be used with standard AWS tooling to interact with SQS can be obtained by calling the `/token` endpoint. Both a valid TLS certificate and an API key must be supplied with the token request. Note that the token endpoint is not versioned.
35+
36+
### Example: Create and Read a Temporary SQS Token
37+
38+
To make an authenticated token request to the API using the client-specific TLS certificate, private key and API key:
39+
40+
```sh
41+
curl --cert <client-cert-file> --key <client-key-file> -X POST https://<environment>.integration-api.hmpps.service.justice.gov.uk/token -H 'x-api-key: <api-key>'
42+
```

‎tech-docs/source/documentation/adr/index.html.md.erb

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Architecture Decision Records
3+
weight: 9
4+
owner_slack: "#hmpps-integration-api-alerts"
5+
last_reviewed_on: 2024-09-03
6+
review_in: 3 months
7+
---
8+
9+
# Relevant Architecture Decision Records
10+
11+
| Status | Adr No. | Title |
12+
|----------------------------------------------------|---------|-------------------------------------------|
13+
| <strong class="govuk-tag--green">ACCEPTED</strong> | 0004 | [Always return a JSON object for JSON responses](https://github.com/ministryofjustice/hmpps-integration-api/blob/main/docs/adr/0004-always-return-a-json-object-for-json-responses.md) |
14+
| <strong class="govuk-tag--green">ACCEPTED</strong> | 0006 | [URL-encode path parameters that contain a forward slash](https://github.com/ministryofjustice/hmpps-integration-api/blob/main/docs/adr/0006-url-encode-path-parameters.md) |
15+
| <strong class="govuk-tag--green">ACCEPTED</strong> | 0007 | [Version through URL path](https://github.com/ministryofjustice/hmpps-integration-api/blob/main/docs/adr/0007-version-through-url-path.md) |

0 commit comments

Comments
 (0)