This is a RESTful API Specification for the Proxygen service in OAS v3.0 format. It is published on the API Catalogue.
Proxygen is an internal-use NHS England service for API Producer teams building and running services on the API Management platform.
The Proxygen implementation is found in the api-management-infrastructure repo.
specification/This Open API Specification describes the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers.scripts/Utilities helpful to developers of this specification..github/GitHub Actions workflows automating the Software Development Lifecycle of this repository.
Contributions to this project are welcome from anyone, providing that they conform to the guidelines for contribution and the community code of conduct.
This code is dual licensed under the MIT license and the OGL (Open Government License). Any new work added to this repository must conform to the conditions of these licenses. In particular this means that this project may not depend on GPL-licensed or AGPL-licensed libraries, as these would violate the terms of those libraries' licenses.
The contents of this repository are protected by Crown Copyright (C).
The SDLC is driven by a number of GitHub Actions workflows defined in .github/workflows/:
pr-lint.ymlPR Quality Check When a PR is opened: branch name is checked for conformity to agreed format; helpful information is added to the PR; OAS spec is linted.publish-to-uat.ymlPublish Spec to Bloomreach UAT Portal Run manually to publish a specification from any branch to the UAT Portal for previewing.release.ymlCreate Release and Publish to Live API Catalogue On merging tomaina new release is created and the specification is updated on the API Catalogue.
- Create a branch. The name must include a JIRA ticket reference.
- Make changes to the specification (see OAS Authoring, below)
- Open a Pull Request for a colleague to review.
- On successful review, and successful completion of the PR Quality Check pipeline, merge to
main - Specification is published to the API Catalogue
Manually run the Publish Spec to Bloomreach UAT Portal against any branch to publish a preview to the UAT Portal. Only one preview can be published at a time.
The specification is a collection of YAML files and can be modified with any text editor. However a number of tools are available to make the process easier.
The openapi.tools website lists a number of GUI Editors. Or you can find a plugin for your favourite text editor. Some suggestions below.
- openapi-yaml-mode provides syntax highlighting, completion, and path help
OAS Specifications have a mandatory info.version property indicating the version of the specification. In the repository it is set to __VERSION__ and is populated during deployment.
On merge to main a release is created and the version is calculated from commits using the scripts/calculate_version.py script.
When publishing a preview using the Publish Spec to Bloomreach UAT Portal Workflow the info.version is set to <branch_name>-<commit_SHA>
This repo is for an OAS specification file. As such there are no dependencies per se however the following utilities are used by the GitHub actions workflows:
- vacuum An OpenAPI linter
- proxygen-cli Deploys the specification
The Github workflows use the Proxygen CLI to perform automated deployment and therefore require some secrets to be defined. The current values for these are always stored in the APIM Prod AWS Secrets Manager.
| Workflow Variable | AWS SM Path |
|---|---|
| PROXYGEN_CLIENT_ID | prod/proxygen-api-specification/client_id |
| PROXYGEN_KID | prod/proxygen-api-specification/key_id |
| ENCODED_PROXYGEN_PRIVATE_KEY | prod/proxygen-api-specification/keycloak_client_private_key |