tewhatuora/api-standards

Health New Zealand | Te Whatu Ora API Development and Security Standards

This GitHub project is the source repository for the Health NZ API Development and Security Standards project, which are officially published at https://apistandards.digital.health.nz.

View standards website · Submit feedback

Table of Contents

Getting Started
- Installation
Contributing
License

Getting Started

Content editing

To edit the API Standards content, edits can be made to the Markdown files in the docs folder of the project. To edit these files, any text editor can be used, or the GitHub user interface. This step is all that is required to make changes to the standards content.

Running the Standards website in development

Note that these steps are only required to run the website locally, and are not strictly required to modify content of the Standards. To modify the website itself in a local development environment, for

Installation

Install the Node.js runtime.

Clone the repo

git clone https://github.com/tewhatuora/api-standards.git

Install NPM packages
```
npm install
```
Start the website in development
```
npm start
```

Spell check and formatting

There is are npm scripts that will check the spelling and formatting of changes to the docs.

Run markdown linting:

npm run markdownlint

Run a spell check:

npm run spellcheck

Any words that do not appear in the default dictionaries can be added to the projects dictionaries defined here.

Any issues with the markdown linting can be overridden across the project in the configuration file .markdownlint.jsonc or overridden per file by adding the following comment to the file.

<!-- markdownlint-disable MD024 MD036 MD040 MD041 MD051 -->

Standards authoring

There is an component which is used to auto-generate tooltips and a master checklist of all standards. On build, a script (/scripts/extractStandards.js) runs which parses these components and generates the master checklist and tooltips.

Basic Usage

To wrap a piece of text in an ApiStandard component, use the following structure:


<ApiStandard id="UNIQUE_ID" type="RULE_TYPE" toolTip="Description of the rule." wrapper="li">

  Your text here

</ApiStandard>

Example


<ApiStandard id="HNZAS_MUST_USE_TLS" type="MUST" toolTip="All communications to or from an API MUST use TLS 1.3 or higher." wrapper="li">

  All communications to or from an API **MUST** use TLS 1.3 or higher.

</ApiStandard>

Component Attributes

id: A unique identifier for the rule. It follows the pattern HNZAS_<RULE_TYPE>_<SHORT_DESCRIPTION>.
type: The type of rule, such as MUST, SHOULD, MAY, SHOULD_NOT, MUST_NOT.
toolTip: A brief description that appears as a tooltip when hovering over the rule.
wrapper: The HTML tag used to wrap the text, commonly li for list items or span for inline text.
dupe: A boolean attribute that indicates if the rule is a duplicate of another rule. This is used to prevent the rule from being included twice in the master checklist.

Trends and Common Patterns

Single Line Rules

When documenting simple rules, wrap the rule text in an ApiStandard component:


<ApiStandard id="HNZAS_SHOULD_HAVE_HOME_PAGE" type="SHOULD" toolTip="A FHIR IG should have a home page with a clear high level description of the implementation." wrapper="li">

  A FHIR IG **SHOULD** have a home page: "A clear high level description of the implementation"

</ApiStandard>

Multiple Sentences

For more complex rules that span multiple sentences, ensure each sentence is clear and the entire rule is wrapped:


<ApiStandard id="HNZAS_MUST_PUBLISH_CAPABILITY_STATEMENT" type="MUST" toolTip="FHIR APIs MUST publish a CapabilityStatement resource at the {{API_URL}}/metadata endpoint." wrapper="li">

  FHIR APIs **MUST** publish a **CapabilityStatement** resource at the `{{API_URL}}/metadata` endpoint.

</ApiStandard>

Lists of Requirements

When listing multiple requirements, each item should be wrapped individually:


<ApiStandard id="HNZAS_MUST_USE_TLS" type="MUST" toolTip="All communications to or from an API MUST use TLS 1.3 or higher." wrapper="li">

  All communications to or from an API **MUST** use TLS 1.3 or higher.

</ApiStandard>

<ApiStandard id="HNZAS_MUST_ENCRYPT_TOKENS" type="MUST" toolTip="Tokens MUST be encrypted." wrapper="li">

  Tokens **MUST** be encrypted.

</ApiStandard>