CMSNAV-798: Update content API development operation

.gitignore

@@ -1,3 +1,5 @@
+.env
+test-report.xml
 
 .direnv
 node_modules/

Makefile

@@ -1,5 +1,11 @@
 SHELL=/bin/bash -euo pipefail
 
+# Only include .env if it exists.
+ifneq ("$(wildcard .env)","")
+	include .env
+	export
+endif
+
 #Installs dependencies using poetry.
 install-python:
 	poetry install
@@ -31,6 +37,10 @@ publish: clean
 	mkdir -p build
 	npm run publish 2> /dev/null
 
+#Serve the API description locally
+serve:
+	npm run serve
+
 #Runs build proxy script
 build-proxy:
 	scripts/build_proxy.sh
@@ -46,6 +56,9 @@ release: clean publish build-proxy
 	cp ecs-proxies-deploy.yml dist/ecs-deploy-internal-qa-sandbox.yml
 	cp ecs-proxies-deploy.yml dist/ecs-deploy-internal-dev-sandbox.yml
 
+token:
+	SSO_LOGIN_URL=https://login.apigee.com get_token
+
 #################
 # Test commands #
 #################
@@ -54,7 +67,7 @@ TEST_CMD := @APIGEE_ACCESS_TOKEN=$(APIGEE_ACCESS_TOKEN) \
 		poetry run pytest -v \
 		--color=yes \
 		--api-name=nhs-website-content-api \
-		--proxy-name=$(PROXY_NAME) \
+ 		--proxy-name=$(PROXY_NAME) \
 		-s
 
 PROD_TEST_CMD := $(TEST_CMD) \
@@ -69,7 +82,7 @@ smoketest:
 
 test:
 	$(TEST_CMD) \
-	--junitxml=test-report.xml \
+	--junitxml=test-report.xml
 
 smoketest-prod:
 	$(PROD_TEST_CMD) \
@@ -78,4 +91,4 @@ smoketest-prod:
 
 test-prod:
 	$(PROD_CMD) \
-	--junitxml=test-report.xml \
+	--junitxml=test-report.xml

README.md

@@ -19,156 +19,29 @@ This code is dual licensed under the MIT license and the OGL (Open Government Li
 
 The contents of this repository are protected by Crown Copyright (C).
 
-## Development
+## Quick Start
+
+### Prerequisites
 
-### Requirements
 * make
 * nodejs + npm/yarn
-* [poetry](https://github.com/python-poetry/poetry)
+* poetry
 * Java 8+
 
-### Install
-```
-$ make install
-```
-
-#### Updating hooks
-You can install some pre-commit hooks to ensure you can't commit invalid spec changes by accident. These are also run
-in CI, but it's useful to run them locally too.
-
-```
-$ make install-hooks
-```
-
-### Environment Variables
-Various scripts and commands rely on environment variables being set. These are documented with the commands.
-
-:bulb: Consider using [direnv](https://direnv.net/) to manage your environment variables during development and maintaining your own `.envrc` file - the values of these variables will be specific to you and/or sensitive.
-
-### Make commands
-There are `make` commands that alias some of this functionality:
- * `lint` -- Lints the spec and code
- * `publish` -- Outputs the specification as a **single file** into the `build/` directory
- * `serve` -- Serves a preview of the specification in human-readable format
-
-### Testing
-Each API and team is unique. We encourage you to use a `test/` folder in the root of the project, and use whatever testing frameworks or apps your team feels comfortable with. It is important that the URL your test points to be configurable. We have included some stubs in the Makefile for running tests.
-
-### VS Code Plugins
-
- * [openapi-lint](https://marketplace.visualstudio.com/items?itemName=mermade.openapi-lint) resolves links and validates entire spec with the 'OpenAPI Resolve and Validate' command
- * [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) provides sidebar navigation
-
-
-### Emacs Plugins
-
- * [**openapi-yaml-mode**](https://github.com/esc-emacs/openapi-yaml-mode) provides syntax highlighting, completion, and path help
-
-### Speccy
-
-> [Speccy](http://speccy.io/) *A handy toolkit for OpenAPI, with a linter to enforce quality rules, documentation rendering, and resolution.*
-
-Speccy does the lifting for the following npm scripts:
-
- * `test` -- Lints the definition
- * `publish` -- Outputs the specification as a **single file** into the `build/` directory
- * `serve` -- Serves a preview of the specification in human-readable format
-
-(Workflow detailed in a [post](https://developerjack.com/blog/2018/maintaining-large-design-first-api-specs/) on the *developerjack* blog.)
-
-:bulb: The `publish` command is useful when uploading to Apigee which requires the spec as a single file.
-
-### Caveats
-
-#### Swagger UI
-Swagger UI unfortunately doesn't correctly render `$ref`s in examples, so use `speccy serve` instead.
-
-#### Apigee Portal
-The Apigee portal will not automatically pull examples from schemas, you must specify them manually.
-
-### Platform setup
-
-As currently defined in your `proxies` folder, your proxies do pretty much nothing.
-Telling Apigee how to connect to your backend requires a *Target Server*, which you should call named `nhs-website-content-api-target`.
-Our *Target Servers* defined in the [api-management-infrastructure](https://github.com/NHSDigital/api-management-infrastructure) repository.
-
-:bulb: For Sandbox-running environments (`test`) these need to be present for successful deployment but can be set to empty/dummy values.
-
-### Detailed folder walk through
-To get started developing your API use this template repo alongside guidance provided by the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Deliver+your+API)
-
-#### `/.github`:
-
-This folder contains templates that can be customised for items such as opening pull requests or issues within the repo
-
-`/.github/workflows`: This folder contains templates for github action workflows such as:
-- `pr-lint.yaml`: This workflow template shows how to link Pull Request's to Jira tickets and runs when a pull request is opened.
-- `continuous-integration.yml`: This workflow template shows how to publish a Github release when pushing to master.
-
-#### `/azure`:
-
-Contains templates defining Azure Devops pipelines. By default the following pipelines are available:
--  `azure-build-pipeline.yml`: Assembles the contents of your repository into a single file ("artifact") on Azure Devops and pushes any containers to our Docker registry. By default this pipeline is enabled for all branches.
-- `azure-pr-pipeline.yml`: Deploys ephemeral versions of your proxy/spec to Apigee (and docker containers on AWS) to internal environments. You can run automated and manual tests against these while you develop. By default this pipeline will deploy to internal-dev, but the template can be amended to add other environments as required.
-- `azure-release-pipeline.yml`: Deploys the long-lived version of your pipeline to internal and external environments, typically when you merge to master.
-
-The `project.yml` file needs to be populated with your service names to make them available to the pipelines
-
-`/azure/templates`: Here you can define reusable actions, such as running tests, and call these actions during Azure Devops pipelines. 
-
-#### `/proxies`:
-
-This folder contains files relating to your Apigee API proxy.
-
-There are 2 folders `/live` and `/sandbox` allowing you to define a different proxy for sandbox use. By default, this sandbox proxy is implemented to route to the sandbox target server (code for this sandbox is found under /sandbox of this template repo)
-
-Within the `live/apiproxy` and `sandbox/apiproxy` folders are:
-
-`/proxies/default.xml`: Defines the proxy's Flows. Flows define how the proxy should handle different requests. By default, _ping and _status endpoint flows are defined.
-See the APM confluence for more information on how the [_ping](https://nhsd-confluence.digital.nhs.uk/display/APM/_ping+endpoint) and [_status](https://nhsd-confluence.digital.nhs.uk/display/APM/_status+endpoint) endpoints work.
-
-`/policies`: Populated with a set of standard XML Apigee policies that can be used in flows.
-
-`/resources/jsc`: Snippets of javascript code that are used in Apigee Javascript policies. For more info about Javascript policies see [here](https://docs.apigee.com/api-platform/reference/policies/javascript-policy)
-
-`/targets`: The XMLs within these folders set up target definitions which allow connections to external target servers. The sandbox target definition is implemented to route to the sandbox target server (code for this sandbox is found under /sandbox of this template repo). For more info on setting up a target server see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Setting+up+a+target+server)
-
-#### `/sandbox`:
-
-This folder contains a template for a sandbox API. This example is a NodeJs application running in Docker. The application handles a few simple endpoints such as: /_ping, /health, /_status, /hello and some logging logic.
-For more information about building sandbox APIs see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Setting+up+your+API+sandbox ).
-
-#### `/scripts`:
-
-Contains useful scripts that are used throughout the project, for example in Makefile and Github workflows
-
-#### `/specification`:
-
-Create an OpenAPI Specification to document your API. For more information about developing specifications see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Documenting+your+API).
-
-#### `/tests`:
-
-End-to-end tests. These tests are written in Python and use the PyTest test runner. Before running these tests you will need to set environment variables. The `test_endpoint.py` file provides a template of how to set up tests which test your api endpoints. For more information about testing your API see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Testing+your+API ).
-
-#### `Makefile`:
-Useful `make` targets to get started including: installing dependencies and running smoke tests.
-
-#### `ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:
-
-These files are required to deploy containers alongside your Apigee proxy during the Azure Devops `azure-build-pipeline`. In this template repo we are deploying our sandbox container which is used as the target server for the sandbox proxy.
-
-`ecs-proxies-containers.yml`: The path to a container's Dockerfile is defined here. This path needs to be defined to allow containers to be pushed to our repository during the `azure-build-pipeline`.
-
-`ecs-proxies-deploy.yml` : Here you can define config for your container deployment.  
-
-For more information about deploying ECS containers see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Developing+ECS+proxies#DevelopingECSproxies-Buildingandpushingdockercontainers ).
+Consider using a **dev container**. While this is in no way a requirement, you may find it more convenient.
 
-#### `manifest_template.yml`:
+### Get Environmental Variables
 
-This file defines 2 dictionaries of fields that are required for the Apigee deployment. For more info see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Manifest.yml+reference ).
+1. Make a new `.env` file in this directory, using `example.env` as a base.
+1. Fill in the missing environmental variables:
+    - At the time of writing, `PROXY_NAME` should be set to `nhs-website-content-api-internal-dev`.
+    - You can get an `APIGEE_ACCESS_TOKEN` via the `get_token` command. If you don't already have access to the `get_token` command, you can install it using [these instructions](https://docs.apigee.com/api-platform/system-administration/auth-tools#install).
+    - You can get the latest `SOURCE_COMMIT_ID` via the `/_ping` endpoint of the proxy you're using. For example, with `PROXY_NAME` set to `nhs-website-content-api-internal-dev`, we would want to access the URL https://internal-dev.api.service.nhs.uk/nhs-website-content/_ping - this should return some JSON, and the value we want has key `commitId`.
 
-#### Package management:
+:bulb: The `make token` command provides a useful shorthand for calling `get_token` with all the right environmental variables.
 
-This template uses poetry for python dependency management, and uses these files: poetry.lock, poetry.toml, pyproject.toml.
+### Let's Roll
 
-Node dependencies of this template project and some npm scripts are listed in: package.json, package-lock.json..
+1. Install by running `make install` from this directory.
+1. Test this installation by running `make test`, also from this directory.
+1. Try out the preview server by running `make publish` and then `make serve`; then visit the local URL printed in the console.