Deployment Phase Research
Raw Data
This file contains raw search retrieval results or agent logs. The content below shows the original markdown source.
---
layout: raw-data.njk
title: Deployment Phase Research
---
# Deployment Phase Research Results
**Date**: 2025-11-03
**Purpose**: Comprehensive research for API Deployment Phase section of NZ API Standard
**Total searches**: 5
**Total results**: ~124
---
## Search 1: API Versioning Strategies
**Query**: "API versioning strategies"
**Type**: semantic_search
**Limit**: 30
**Results**: 30
### Key Findings
1. **Two Main Methodologies** - Header-based (recommended) and URL-based versioning
2. **Header-Based Versioning Recommended** - Most RESTful, uses Accept header
3. **URL-Based Versioning** - Viable alternative, /vN format with major version only
4. **Breaking vs Non-Breaking Changes** - Version when breaking changes occur
5. **Version Control Beyond Resources** - Include all API artifacts in SCM
6. **Well-Managed APIs** - Good version control and communication with developers
### Results
1. **Versioning Types Introduction** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para1))
- Part: C | Type: para | Level: 2
- Content: "Learn more about the commonly-used types of versioning when developing an API."
- Tags: []
- Score: 0.9152
2. **Two Main Versioning Methodologies** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para2))
- Part: C | Type: para | Level: 2
- Content: "There are 2 main API versioning methodologies commonly used. There are positives and negatives to both approaches and a large amount of debate over which is the most 'RESTful'. Rather than stipulate a methodology to use in these guidelines, each methodology is described below in order of preference. Both, however, are acceptable. What is more important is that APIs are versioned and that there is an understanding of when and why to version an API."
- Tags: [good-practice, should-or-may, standards_review]
- Score: 0.9050
- **Note**: CRITICAL - Both methods acceptable, versioning is what's important
3. **Most RESTful Method** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para4))
- Part: C | Type: para | Level: 2
- Content: "This is usually considered the most RESTful way to version APIs because the resource path remains 'pure' and it is possible to provide more version flexibility for clients. It is, however, technically more difficult to implement and in many cases commercial API management / gateway products do not support or work well with this approach."
- Tags: []
- Score: 0.8986
- **Note**: Refers to header-based versioning
4. **API Version Control Methods Heading** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-h1))
- Part: C | Type: heading | Level: 2
- Content: "1.10.1. API version control methods"
- Tags: []
- Score: 0.8980
5. **Clear Version Indication** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para4))
- Part: C | Type: para | Level: 2
- Content: "APIs should have a clear indication of the version, so that application developers can ensure they are using the appropriate version for their consuming application."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8858
6. **API Version Control Section** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-title))
- Part: C | Type: section | Level: 2
- Content: "1.10. API version control"
- Tags: []
- Score: 0.8837
7. **Planning API Rollout** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para7-2))
- Part: A | Type: para | Level: 3
- Content: "planning API rollout — ensuring all the API artefacts are rolled out effectively and on time to the correct platforms"
- Tags: []
- Score: 0.8805
8. **Header-Based Versioning Recommended** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para5))
- Part: C | Type: para | Level: 2
- Content: "Header-based versioning is **recommended** (see [section 1.10. API version control](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-title)) however, it is recognised that some API infrastructure does not readily support header-based versioning."
- Tags: [definition, definitions, should-or-may, good-practice, standards_review]
- Score: 0.8788
- **Note**: RECOMMENDED - Header-based versioning
9. **Well-Managed APIs** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section8))
- Part: A | Type: section | Level: 1
- Content: "2.8. Well managed As API take-up increases over time, there is more likelihood of API change, redevelopment and adaptation to meet new needs. A well-managed API should handle regular change. API management gives an agency the capability to deliver good version control capability and forewarn application developers of changes that may impact them, including failures and outages. For this reason, it is important that all application developers are identified, even if the API is considered public."
- Tags: [should-or-may, must-or-shall, good-practice, standards_review]
- Score: 0.8780
- **Note**: Version control and developer communication
10. **Version Controlling API Code** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para3-2-2))
- Part: A | Type: para | Level: 4
- Content: "version controlling the associated API code"
- Tags: [definition, definitions]
- Score: 0.8774
11. **Version Control and Developer Communication** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section8-para2))
- Part: A | Type: para | Level: 2
- Content: "API management gives an agency the capability to deliver good version control capability and forewarn application developers of changes that may impact them, including failures and outages. For this reason, it is important that all application developers are identified, even if the API is considered public."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8766
12. **Header-Based Versioning with Accept Header** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para5))
- Part: C | Type: para | Level: 2
- Content: "Header-based versioning should be performed using the Accept header where a consuming application requests an API version as defined in an Accept header. Wildcards (*) are used by the consuming application to indicate acceptance of the latest major or minor version of an API."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8766
13. **Version on Breaking Changes** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para11))
- Part: C | Type: para | Level: 2
- Content: "Simply put, an API should be versioned when a change is considered a breaking change. One of the benefits of an API is that, if it is well designed, there should be fewer breaking changes. In government however, there are likely to be situations where legislative changes enforce a new version of an API and deprecation of all previous versions."
- Tags: [must-or-shall, should-or-may, good-practice, standards_review]
- Score: 0.8762
- **Note**: When to version - breaking changes
14. **Release Management** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para6))
- Part: A | Type: para | Level: 2
- Content: "Release management is an important aspect of API transition. The aim with API development is to make small changes and release often."
- Tags: [definition, definitions, good-practice, should-or-may, standards_review]
- Score: 0.8746
15. **Reduce Effort Through Simplification** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section6-para1-6))
- Part: A | Type: para | Level: 3
- Content: "reduce effort for agencies by simplifying the process of developing and delivering on their API strategies."
- Tags: []
- Score: 0.8740
16. **Configuration Management** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para3-2))
- Part: A | Type: para | Level: 3
- Content: "Configuration management — all the components that make up an instance of the API should be held within version control, so that it is possible to rebuild a previous version, if necessary. This involves:"
- Tags: [definition, definitions]
- Score: 0.8720
17. **Major Version Maintenance** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section6-para3))
- Part: A | Type: para | Level: 2
- Content: "For major changes, which are not backwards compatible, the old API version should be maintained alongside the new version for an appropriate period to allow all-consuming applications to transition. By monitoring usage, it should be possible to assess when an API version can be deprecated, either because it is no longer being used or because the usage pattern does not warrant maintaining that particular version."
- Tags: [should-or-may, good-practice, must-or-shall, standards_review]
- Score: 0.8699
- **Note**: Arguably mandatory - version maintenance for transitions
18. **Part A Title** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#h1))
- Part: A | Type: root | Level: 0
- Content: "API guidelines — Part A: API concepts and management 2022"
- Tags: []
- Score: 0.8694
19. **URL-Based Versioning** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para6))
- Part: C | Type: para | Level: 2
- Content: "URL-based versioning is a viable alternative, as the version number in the URL should only change when major revisions have been made and the interface has changed substantially without backwards compatibility. For URL-based versioning the URI should include /vN with the major version (N) and v as a prefix. Agencies should not include minor version numbers when using version numbers in the API paths."
- Tags: [definition, definitions, should-or-may, good-practice, must-or-shall, standards_review]
- Score: 0.8693
- **Note**: URL-based alternative - /vN format, major version only
20. **URL-Based Versioning (Duplicate)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para8))
- Part: C | Type: para | Level: 2
- Content: "URL-based versioning is a viable alternative, as the version number in the URL should only change when major revisions have been made and the interface has changed substantially without backwards compatibility. For URL-based versioning the URI should include /vN with the major version (N) and v as a prefix. Agencies should not include minor version numbers when using version numbers in the API paths."
- Tags: [definition, definitions, should-or-may, must-or-shall, good-practice, standards_review]
- Score: 0.8693
21. **API Management Heading** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section3-h4))
- Part: A | Type: heading | Level: 2
- Content: "4.3.4. API management"
- Tags: []
- Score: 0.8667
22. **Performance Maximization** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para5-2))
- Part: A | Type: para | Level: 3
- Content: "performance — maximising API efficiency to support consuming applications and minimising downtime"
- Tags: [definition, definitions]
- Score: 0.8648
23. **API Components Section** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1))
- Part: A | Type: section | Level: 1
- Content: "5.1. API components The following are definitions of components that provide API development support capabilities..."
- Tags: [good-practice, standards_review]
- Score: 0.8647
- **Note**: Full section on API gateway, developer portal, API manager
24. **API Release Management Heading** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-h3))
- Part: A | Type: heading | Level: 2
- Content: "4.2.3. API release management"
- Tags: []
- Score: 0.8644
25. **Lifecycle Management of APIs** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para6-tb1-tr2-td2-l4))
- Part: B | Type: list | Level: 6
- Content: "* lifecycle management of APIs"
- Tags: [definition, definitions, reference-examples-apis, substantive_review]
- Score: 0.8643
26. **Stability and Backwards Compatibility** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section6))
- Part: A | Type: section | Level: 1
- Content: "2.6. Stability and backwards compatibility It is important that APIs have stability (are available and work consistently) and support a velocity of change that is acceptable to the application developers. Early versions of APIs should be available via pilots or on developer portals so application developers can work them and identify areas of instability before an API goes into production..."
- Tags: [must-or-shall, good-practice, should-or-may, standards_review]
- Score: 0.8639
- **Note**: CRITICAL - Backwards compatibility, version maintenance
27. **Version Controlling Interface Specifications** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para3-2-1))
- Part: A | Type: para | Level: 4
- Content: "version controlling API interface specifications"
- Tags: [definition, definitions]
- Score: 0.8634
28. **API Design Principles** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h3))
- Part: C | Type: heading | Level: 2
- Content: "1.2.3. API design principles"
- Tags: []
- Score: 0.8631
29. **API Stability Requirements** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section6-para1))
- Part: A | Type: para | Level: 2
- Content: "It is important that APIs have stability (are available and work consistently) and support a velocity of change that is acceptable to the application developers. Early versions of APIs should be available via pilots or on developer portals so application developers can work them and identify areas of instability before an API goes into production."
- Tags: [good-practice, should-or-may, must-or-shall, standards_review]
- Score: 0.8628
- **Note**: Arguably mandatory
30. **API Strategy Evolution** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section6-para5))
- Part: A | Type: para | Level: 2
- Content: "While organisations across government have different levels of take-up in terms of APIs, there is a common pattern of evolution, which can help when developing an API strategy and road mapping delivery of APIs."
- Tags: [api-guidelines-review-notes, substantive_review]
- Score: 0.8626
---
## Search 2: API Gateway Deployment
**Query**: "API gateway deployment"
**Type**: semantic_search
**Limit**: 30
**Results**: 30
### Key Findings
1. **API Gateway Definition** - Delivery component that hosts APIs for outside world access
2. **API Gateway Capabilities** - Policy enforcement, security, performance, QoS, throttling
3. **API Gateway as PEP** - Policy Enforcement Point for access control
4. **Three Core Components** - API developer portal, API gateway, API manager
5. **Gateway Responsibilities** - Authentication, authorization, threat protection, monitoring
### Results
1. **API Gateway (Security Table)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para6-tb1-tr3-td1))
- Part: B | Type: table | Level: 5
- Content: "API gateway"
- Tags: [definition, definitions, reference-examples-apis, substantive_review]
- Score: 0.9322
2. **API Gateway (Figure Reference)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-fig3-det1-para2-3))
- Part: B | Type: para | Level: 5
- Content: "API gateway"
- Tags: [reference-examples-apis, figures, substantive_review]
- Score: 0.9322
3. **API Gateway Section Heading** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section5-h5))
- Part: B | Type: heading | Level: 2
- Content: "3.5.4. API gateway"
- Tags: []
- Score: 0.9190
4. **API in the API Gateway** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section1-fig1-det1-para3-3))
- Part: B | Type: para | Level: 5
- Content: "API in the API gateway"
- Tags: [figures, substantive_review]
- Score: 0.9168
5. **API Gateway Section (Part A)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-h2))
- Part: A | Type: heading | Level: 2
- Content: "5.1.2. API gateway"
- Tags: []
- Score: 0.9163
6. **API Gateway Definition (Part C)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part8-para1-l6))
- Part: C | Type: list | Level: 2
- Content: "==API gateway== The API delivery component that allows API providers to offer APIs to the outside world. This component (physical or virtual) hosts the APIs ready for consumers to access. It provides an API provider with the ability to control who has access to their APIs by enforcing policies for access control. Some API gateways also offer additional capabilities."
- Tags: [definition, definitions]
- Score: 0.9125
- **Note**: Primary definition
7. **API Gateway Definition (Part A)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part7-para1-l6))
- Part: A | Type: list | Level: 2
- Content: "==API gateway== The API delivery component that allows API providers to offer APIs to the outside world. This component (physical or virtual) hosts the APIs ready for consumers to access. It provides an API provider with the ability to control who has access to their APIs by enforcing policies for access control. Some API gateways also offer additional capabilities."
- Tags: [definition, definitions]
- Score: 0.9125
8. **API Gateway Definition (Part B)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part14-para1-l6))
- Part: B | Type: list | Level: 2
- Content: "==API gateway== The API delivery component that allows API providers to offer APIs to the outside world. This component (physical or virtual) hosts the APIs ready for consumers to access. It provides an API provider with the ability to control who has access to their APIs by enforcing policies for access control. Some API gateways also offer additional capabilities."
- Tags: [definition, definitions]
- Score: 0.9125
9. **API Gateway Capabilities** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para6-tb1-tr3-td2-l1))
- Part: B | Type: list | Level: 6
- Content: "The API gateway capability can:"
- Tags: [definition, definitions, reference-examples-apis, substantive_review]
- Score: 0.9000
10. **API Gateway for Safe Access** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-para1-3-2))
- Part: A | Type: para | Level: 3
- Content: "API gateway — for ensuring safe access to your APIs"
- Tags: [definition, definitions]
- Score: 0.8996
11. **API Gateway Description** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para4))
- Part: A | Type: para | Level: 2
- Content: "The API gateway is the means through which APIs are offered to the outside world. This component (physical or virtual) hosts the APIs ready for consumers to access. It provides an agency with the ability to control who has access to their APIs by enforcing policies for access control."
- Tags: [definition, definitions]
- Score: 0.8994
12. **API Gateway Proprietary (Pattern 1)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det1-para1-3))
- Part: B | Type: para | Level: 4
- Content: "API gateway proprietary."
- Tags: [patterns, substantive_review]
- Score: 0.8945
13. **API Gateway Proprietary (Pattern 6)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det6-para1-3))
- Part: B | Type: para | Level: 4
- Content: "API gateway proprietary."
- Tags: [patterns, substantive_review]
- Score: 0.8945
14. **API Gateway Proprietary (Pattern 5)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det5-para1-4))
- Part: B | Type: para | Level: 4
- Content: "API gateway proprietary."
- Tags: [patterns, substantive_review]
- Score: 0.8945
15. **API Gateway Proprietary (Pattern 4)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det4-para1-2))
- Part: B | Type: para | Level: 4
- Content: "API gateway proprietary."
- Tags: [patterns, substantive_review]
- Score: 0.8945
16. **API Gateway Proprietary (Pattern 7)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det7-para1-4))
- Part: B | Type: para | Level: 4
- Content: "API gateway proprietary."
- Tags: [patterns, substantive_review]
- Score: 0.8945
17. **API Gateway Capabilities Table** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para6-tb1-tr3))
- Part: B | Type: table | Level: 4
- Content: "API gateway The API gateway capability can: * act as the API proxy or the host acting as the primary point of access for exposed APIs * enforce threat protection, throttling and quota management * provide authorisation services to control access to APIs * provide authentication services to ensure only permitted users (internal / external) have access to the API * enforce security policy * provide monitoring and analytics for business and security analysts."
- Tags: [reference-examples-apis, substantive_review]
- Score: 0.8939
- **Note**: CRITICAL - Full list of gateway capabilities
18. **Gateway Hosts Published APIs** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-fig7-det1-para1-4))
- Part: A | Type: para | Level: 5
- Content: "the API gateway hosts the API after it is published by the API manager"
- Tags: [definition, definitions]
- Score: 0.8902
19. **Gateway as Policy Enforcement Point** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para5))
- Part: A | Type: para | Level: 2
- Content: "The gateway is sometimes referred to as the API policy enforcement point. Some API gateways also offer additional capabilities such as:"
- Tags: [definition, definitions]
- Score: 0.8901
20. **Response to API Gateway** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section12-fig3-det1-para8-20))
- Part: C | Type: para | Level: 5
- Content: "Providing application sends response to API gateway."
- Tags: [figures, substantive_review]
- Score: 0.8888
21. **Response to API Gateway (Duplicate)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section12-fig3-det1-para2-6))
- Part: C | Type: para | Level: 5
- Content: "Providing application sends response to API gateway."
- Tags: [figures, substantive_review]
- Score: 0.8888
22. **API Gateway Full Capabilities** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para6-tb1-tr3-td2))
- Part: B | Type: table | Level: 5
- Content: "The API gateway capability can: * act as the API proxy or the host acting as the primary point of access for exposed APIs * enforce threat protection, throttling and quota management * provide authorisation services to control access to APIs * provide authentication services to ensure only permitted users (internal / external) have access to the API * enforce security policy * provide monitoring and analytics for business and security analysts."
- Tags: [definition, definitions, reference-examples-apis, substantive_review]
- Score: 0.8880
23. **Gateway Sends Process Request** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section12-fig3-det1-para9-28))
- Part: C | Type: para | Level: 5
- Content: "API gateway sends process request to providing application."
- Tags: [figures, substantive_review]
- Score: 0.8840
24. **Gateway Sends Process Request (Multiple)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section12-fig3-det1-para2-4))
- Part: C | Type: para | Level: 5
- Content: "API gateway sends process request to providing application."
- Tags: [figures, substantive_review]
- Score: 0.8840
25. **Gateway Sends Process Request (More)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section12-fig3-det1-para8-18))
- Part: C | Type: para | Level: 5
- Content: "API gateway sends process request to providing application."
- Tags: [figures, substantive_review]
- Score: 0.8840
26. **Gateway Sends Process Request (Additional)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section12-fig3-det1-para10-36))
- Part: C | Type: para | Level: 5
- Content: "API gateway sends process request to providing application."
- Tags: [figures, substantive_review]
- Score: 0.8840
27. **Response with Updated Data** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section12-fig3-det1-para9-30))
- Part: C | Type: para | Level: 5
- Content: "Providing application sends response with updated data to API gateway."
- Tags: [figures, substantive_review]
- Score: 0.8799
28. **Response with Updated Data (Duplicate)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section12-fig3-det1-para10-38))
- Part: C | Type: para | Level: 5
- Content: "Providing application sends response with updated data to API gateway."
- Tags: [figures, substantive_review]
- Score: 0.8799
29. **Gateway Protection Capabilities** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section7-para3))
- Part: B | Type: para | Level: 2
- Content: "API gateway capabilities can protect against many typical API vulnerabilities and threats. Typically, these relate to:"
- Tags: []
- Score: 0.8786
30. **Gateway OAuth Support** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section5-para19))
- Part: B | Type: para | Level: 2
- Content: "API gateways have been mentioned previously in the context of API protection. Most API gateways on the market provide support for OAuth 2.0 and can also provide authorisation (and authentication) services via a direct connection to:"
- Tags: []
- Score: 0.8735
---
## Search 3: API Documentation Requirements
**Query**: "API documentation requirements"
**Type**: semantic_search
**Limit**: 30
**Results**: 30
### Key Findings
1. **API Documentation Component** - Technical descriptions and reference models
2. **Documentation Must Be Well-Maintained** - External APIs must be well documented
3. **Machine-Readable Specifications** - Should be provided in machine-readable format
4. **API Catalogue Requirements** - Up-to-date and accurate information
5. **Developer Portal Education** - Providing developers with necessary information
6. **Documentation as Part of API Artefacts** - Included in registration and management
### Results
1. **API Documentation (Security Table)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para6-tb1-tr5-td1))
- Part: B | Type: table | Level: 5
- Content: "API documentation"
- Tags: [definition, definitions, reference-examples-apis, substantive_review]
- Score: 0.9272
2. **API Documentation (Figure Reference)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-fig3-det1-para2-5))
- Part: B | Type: para | Level: 5
- Content: "API documentation"
- Tags: [reference-examples-apis, figures, substantive_review]
- Score: 0.9272
3. **Part C Title** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#h1))
- Part: C | Type: root | Level: 0
- Content: "API guidelines — Part C: API development 2022"
- Tags: []
- Score: 0.8901
4. **Part A Title** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#h1))
- Part: A | Type: root | Level: 0
- Content: "API guidelines — Part A: API concepts and management 2022"
- Tags: []
- Score: 0.8842
5. **Standards for Developing APIs** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part7-para1))
- Part: C | Type: para | Level: 1
- Content: "Learn more about the relevant standards for developing APIs."
- Tags: []
- Score: 0.8827
6. **Standards Table Caption** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part7-para3-tb1-caption))
- Part: C | Type: table | Level: 3
- Content: "Table 7: Standards for developing APIs"
- Tags: []
- Score: 0.8822
7. **Definitions Section** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section2-title))
- Part: B | Type: section | Level: 2
- Content: "1.2. Definitions for APIs covered in these guidelines"
- Tags: [definition, definitions]
- Score: 0.8810
8. **Part C Introduction** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#para1))
- Part: C | Type: root | Level: 0
- Content: "Learn about the technical details in developing an API (Application Programming Interface) and the standards that need to be met."
- Tags: []
- Score: 0.8808
9. **Appendix E Title** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part7-title))
- Part: C | Type: part | Level: 1
- Content: "7. Appendix E — Standards for developing APIs"
- Tags: []
- Score: 0.8780
10. **API Functional Requirements** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-para2))
- Part: A | Type: para | Level: 1
- Content: "An API should strive to deliver these functional and non-functional requirements:"
- Tags: [definition, definitions, api-guidelines-review-notes, specific-system-requirements, drafting-and-expression, substantive_review, should-or-may, good-practice, to-review, must-or-shall, standards_review]
- Score: 0.8754
- **Note**: Annotation says "These are actually mandatory"
11. **Well-Documented External APIs** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para61))
- Part: C | Type: para | Level: 2
- Content: "Once an API is in sufficient state to be offered to API consumers, the API definition should be published to an API catalogue. The primary API discoverer is the developer, so an external API must be well documented, and provide accurate and up-to-date guidance via the catalogue."
- Tags: [definition, definitions, catalogue, substantive_review, should-or-may, must-or-shall, good-practice, standards_review]
- Score: 0.8725
- **Note**: MANDATORY - Well documented, accurate, up-to-date
12. **Requirements Extraction** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para25))
- Part: C | Type: para | Level: 2
- Content: "When representatives for the potential actors are identified, start co-designing with these representatives. First and foremost consider the requirements for the API. Application developers often couch their requirements in terms of how the API should work, rather than what the API needs to do. Do not get bogged down in the variety of proposed solutions from each developer. Focus on extracting the true requirements by performing functional analysis (for example, use cases) and data flow analysis, and then identify resources and work out the granularity (see [section 1.2.7. Granularity](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h10))."
- Tags: [good-practice, should-or-may, standards_review]
- Score: 0.8704
13. **Education for Developers** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para3-3))
- Part: A | Type: para | Level: 3
- Content: "education — providing developers with the information they need to make use of APIs"
- Tags: [definition, definitions]
- Score: 0.8683
14. **Required Unless Public API** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb1-tr3-td6))
- Part: C | Type: table | Level: 4
- Content: "Required, unless a public API"
- Tags: []
- Score: 0.8681
15. **Required Unless Public API (Multiple)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb1-tr3-td4))
- Part: C | Type: table | Level: 4
- Content: "Required, unless a public API"
- Tags: []
- Score: 0.8681
16. **Required Unless Public API (More)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb1-tr3-td3))
- Part: C | Type: table | Level: 4
- Content: "Required, unless a public API"
- Tags: []
- Score: 0.8681
17. **Required Unless Public API (Additional)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb1-tr3-td5))
- Part: C | Type: table | Level: 4
- Content: "Required, unless a public API"
- Tags: []
- Score: 0.8681
18. **API Catalogue Information** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para5))
- Part: A | Type: para | Level: 2
- Content: "The API catalogue will contain a list of all the APIs offered, along with their interface specifications and guidance on how to gain access, and use the APIs, including the granularity of access control. This information needs to be up to date and accurate in order to be relied upon by API application developers."
- Tags: [definition, definitions]
- Score: 0.8680
19. **Part A Principles Referenced** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para9))
- Part: C | Type: para | Level: 2
- Content: "This section assumes that API principles defined in [Part A: API concepts and managment 2022](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/) of these guidelines have already been read."
- Tags: [definition, definitions]
- Score: 0.8674
20. **Why Have API Guidelines** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section6-title))
- Part: A | Type: section | Level: 2
- Content: "1.6. Why have API guidelines"
- Tags: []
- Score: 0.8660
21. **API Design and Development** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-title))
- Part: C | Type: part | Level: 1
- Content: "1. API design and development"
- Tags: []
- Score: 0.8657
22. **When an API is Appropriate** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h1))
- Part: C | Type: heading | Level: 2
- Content: "1.2.1. When an API is appropriate"
- Tags: []
- Score: 0.8649
23. **Needs and Drivers Section** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section5))
- Part: A | Type: section | Level: 1
- Content: "1.5. Needs and drivers So why build an API? In what situation is an API the right thing to develop?..."
- Tags: [good-practice, standards_review]
- Score: 0.8644
24. **API Architecture Figure** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-fig7))
- Part: A | Type: figure | Level: 2
- Content: "Figure 8: API core components and capabilities..."
- Tags: [good-practice, standards_review]
- Score: 0.8642
25. **Machine-Readable Specifications** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para9))
- Part: A | Type: para | Level: 2
- Content: "An API interface specification is a technical description and reference model for an API. The specification is used most commonly by application developers to understand the technical aspects of an API. However, interface specifications should also be provided in a machine-readable format. Refer to [Part C: API development 2022](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/) for details."
- Tags: [definition, definitions, reference-examples-apis, substantive_review, should-or-may, good-practice, must-or-shall, standards_review]
- Score: 0.8639
- **Note**: Annotated as "Arguably should be mandatory"
26. **Managing Application Developers** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para2))
- Part: A | Type: para | Level: 2
- Content: "Agencies developing APIs need to be able to engage, onboard, educate and manage consuming application developers, whether inside or outside the organisation. These management activities will generally include registration, documentation, analytics and so on."
- Tags: [definition, definitions]
- Score: 0.8621
27. **Key Characteristics of an API** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-title))
- Part: A | Type: part | Level: 1
- Content: "3. Key characteristics of an API"
- Tags: [definition, definitions]
- Score: 0.8617
28. **Part B Title** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#h1))
- Part: B | Type: root | Level: 0
- Content: "API guidelines — Part B: API security 2022"
- Tags: []
- Score: 0.8615
29. **Basic Capabilities for API Support** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-para1-3))
- Part: A | Type: para | Level: 2
- Content: "Have the following basic capabilities set up to support development, discovery of and access to your API:"
- Tags: []
- Score: 0.8612
30. **API Architecture Components** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-fig7-det1))
- Part: A | Type: figure | Level: 3
- Content: "Detailed description of figure Figure 8 illustrates a general API architecture that includes the core components and capabilities of an API..."
- Tags: []
- Score: 0.8611
---
## Search 4: Deployment Good Practices
**Query**: "deployment"
**Type**: semantic_search_filtered
**Filters**: tags=["good-practice"]
**Limit**: 30
**Results**: 4
### Key Findings
1. **Architectural and Deployment Patterns** - Table 2 identifies patterns worth investigating
2. **Agile Practices** - Iterative development, failing fast, frequent delivery
3. **Small Changes, Release Often** - Aim with API development
4. **Loosely Coupled Architecture** - Highly distributed and loosely coupled
### Results
1. **Architectural and Deployment Patterns** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section3-para1))
- Part: C | Type: para | Level: 1
- Content: "Table 2 identifies some architectural and deployment patterns that bear further investigation. There are a number of vendor specific references that are also available however these guidelines do not recommend any particular one."
- Tags: [patterns, reference-examples-apis, substantive_review, good-practice, should-or-may, standards_review]
- Score: 0.8103
2. **Agile Practices for API Development** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para3-1))
- Part: A | Type: para | Level: 3
- Content: "Agile practices — Agile practices ideally suit this form of iterative development as they focus on developing small, incremental releases, 'failing fast' (finding out what is wrong early rather than too late) and frequent delivery of products"
- Tags: [definition, definitions, good-practice, standards_review]
- Score: 0.8080
- **Note**: Annotated as approaching mandatory but quite specific
3. **Release Management Aim** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para6))
- Part: A | Type: para | Level: 2
- Content: "Release management is an important aspect of API transition. The aim with API development is to make small changes and release often."
- Tags: [definition, definitions, good-practice, should-or-may, standards_review]
- Score: 0.7981
4. **Loosely Coupled Architecture** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part10-para3))
- Part: B | Type: para | Level: 1
- Content: "It is a highly distributed and loosely coupled architecture. It provides very useful generic definitions of the required components (services) that can be used to define any access control model."
- Tags: [good-practice, standards_review]
- Score: 0.7886
---
## Search 5: Versioning (Part C)
**Query**: "versioning"
**Type**: semantic_search_filtered
**Filters**: part="C"
**Limit**: 30
**Results**: 30
### Key Findings
1. **Comprehensive Versioning Section** - Section 1.10 dedicated to version control
2. **Two Methods Detailed** - Accept header versioning and URI path versioning
3. **When to Version** - Breaking changes trigger new versions
4. **Breaking vs Non-Breaking Changes** - Clear definitions provided
5. **Version Format Specifications** - /vN for URL, wildcards for header
6. **Version Control Beyond Versioning** - Include all artifacts in SCM
7. **Response Should Indicate Version** - Using Content-Type or Location header
### Results
1. **Versioning Types Introduction** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para1))
- Part: C | Type: para | Level: N/A
- Content: "Learn more about the commonly-used types of versioning when developing an API."
- Tags: []
- Score: 0.8980
2. **URL-Based Versioning** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para6))
- Part: C | Type: para | Level: 2
- Content: "URL-based versioning is a viable alternative, as the version number in the URL should only change when major revisions have been made and the interface has changed substantially without backwards compatibility. For URL-based versioning the URI should include /vN with the major version (N) and v as a prefix. Agencies should not include minor version numbers when using version numbers in the API paths."
- Tags: [definition, definitions, should-or-may, good-practice, must-or-shall, standards_review]
- Score: 0.8938
- **Note**: MUST NOT include minor versions in paths
3. **URL-Based Versioning (Section 1.10)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para8))
- Part: C | Type: para | Level: 2
- Content: Same as #2
- Tags: [definition, definitions, should-or-may, must-or-shall, good-practice, standards_review]
- Score: 0.8938
4. **Version Template /vN** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para6-ex1-pf1-pfl1))
- Part: C | Type: example | Level: N/A
- Content: "/v{version}/"
- Tags: []
- Score: 0.8816
5. **Version Template (Duplicate)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para6-ex1-pf1))
- Part: C | Type: example | Level: N/A
- Content: "/v{version}/"
- Tags: []
- Score: 0.8816
6. **Header-Based Versioning with Accept** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para5))
- Part: C | Type: para | Level: 2
- Content: "Header-based versioning should be performed using the Accept header where a consuming application requests an API version as defined in an Accept header. Wildcards (*) are used by the consuming application to indicate acceptance of the latest major or minor version of an API."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8732
7. **Accept Header Versioning Heading** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para3))
- Part: C | Type: para | Level: 2
- Content: "**1. Accept header versioning**"
- Tags: []
- Score: 0.8720
8. **Header-Based Versioning Recommended** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para5))
- Part: C | Type: para | Level: 2
- Content: "Header-based versioning is **recommended** (see [section 1.10. API version control](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-title)) however, it is recognised that some API infrastructure does not readily support header-based versioning."
- Tags: [definition, definitions, should-or-may, good-practice, standards_review]
- Score: 0.8688
- **Note**: RECOMMENDED
9. **URI Path Versioning Heading** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para7))
- Part: C | Type: para | Level: 2
- Content: "**2. URI (path) versioning**"
- Tags: []
- Score: 0.8648
10. **When to Version Heading** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-h2))
- Part: C | Type: heading | Level: 2
- Content: "1.10.2. When to version"
- Tags: []
- Score: 0.8622
11. **Version with Namespace Template** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para7-ex1-pf1-pfl1))
- Part: C | Type: example | Level: N/A
- Content: "/{version}/{namespace}/"
- Tags: []
- Score: 0.8617
12. **Version with Namespace Template (Duplicate)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para7-ex1-pf1))
- Part: C | Type: example | Level: N/A
- Content: "/{version}/{namespace}/"
- Tags: []
- Score: 0.8617
13. **Two Main Versioning Methodologies** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para2))
- Part: C | Type: para | Level: 2
- Content: "There are 2 main API versioning methodologies commonly used. There are positives and negatives to both approaches and a large amount of debate over which is the most 'RESTful'. Rather than stipulate a methodology to use in these guidelines, each methodology is described below in order of preference. Both, however, are acceptable. What is more important is that APIs are versioned and that there is an understanding of when and why to version an API."
- Tags: [good-practice, should-or-may, standards_review]
- Score: 0.8603
14. **Clear Version Indication** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para4))
- Part: C | Type: para | Level: 2
- Content: "APIs should have a clear indication of the version, so that application developers can ensure they are using the appropriate version for their consuming application."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8573
15. **Version Template Example** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para6-ex1))
- Part: C | Type: example | Level: N/A
- Content: "Template /v{version}/"
- Tags: []
- Score: 0.8563
16. **Version Control Beyond Resources** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para16))
- Part: C | Type: para | Level: 2
- Content: "It is important to remember that version control is more than just versioning the resource. An API will inherently have associated code and artefacts. Consider what comprises an API and include these as a logical artefact stored and managed in a software configuration management (SCM) system."
- Tags: [definition, definitions, good-practice, should-or-may, standards_review]
- Score: 0.8530
17. **API Version Control Methods** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-h1))
- Part: C | Type: heading | Level: 2
- Content: "1.10.1. API version control methods"
- Tags: []
- Score: 0.8527
18. **Version on Breaking Changes** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para11))
- Part: C | Type: para | Level: 2
- Content: "Simply put, an API should be versioned when a change is considered a breaking change. One of the benefits of an API is that, if it is well designed, there should be fewer breaking changes. In government however, there are likely to be situations where legislative changes enforce a new version of an API and deprecation of all previous versions."
- Tags: [must-or-shall, should-or-may, good-practice, standards_review]
- Score: 0.8519
19. **Accept Header Wildcard Example** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para5-ex1-pf1-pfl13))
- Part: C | Type: example | Level: N/A
- Content: "Accept: application/json, version=*"
- Tags: []
- Score: 0.8500
20. **Response Should Indicate Version** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para10))
- Part: C | Type: para | Level: 2
- Content: "The response should still indicate the version of the API that was called. This can be done as in the example above, using the Content-Type header or in the Location header, as the version in the path indicates the API that was called."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.8482
21. **Breaking Change Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para12))
- Part: C | Type: para | Level: 2
- Content: "A change is a breaking change if any consuming application requires changes to work with the new version. In other words, the new version will not successfully process messages provided by existing consumers. A breaking change should be considered as a major version change, for example, 1.3 to 2.0."
- Tags: [definition, definitions, should-or-may, good-practice, standards_review]
- Score: 0.8480
22. **Most RESTful Method** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para4))
- Part: C | Type: para | Level: 2
- Content: "This is usually considered the most RESTful way to version APIs because the resource path remains 'pure' and it is possible to provide more version flexibility for clients. It is, however, technically more difficult to implement and in many cases commercial API management / gateway products do not support or work well with this approach."
- Tags: []
- Score: 0.8474
23. **Non-Breaking Change Definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para14))
- Part: C | Type: para | Level: 2
- Content: "A change is a non-breaking change if any message that would have been processed by the previous version will be successfully processed by the new version (that is, backwards compatible). This will enable an existing consumer of the previous version to work with the new version without requiring modification. A non-breaking change should be considered as a minor version change, for example, 1.1 to 1.2."
- Tags: [definition, definitions, standards_review]
- Score: 0.8473
24. **Version with Namespace Template Example** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para7-ex1))
- Part: C | Type: example | Level: N/A
- Content: "Template /{version}/{namespace}/"
- Tags: []
- Score: 0.8453
25. **Full Resource Path with Version** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para10-ex1-pf1-pfl2))
- Part: C | Type: example | Level: N/A
- Content: "/{version}/{resource}/{resource-id}/{sub-resource}/{sub-resource-id}"
- Tags: []
- Score: 0.8407
26. **API Version Control Section** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-title))
- Part: C | Type: section | Level: 2
- Content: "1.10. API version control"
- Tags: []
- Score: 0.8385
27. **Full Resource Path Templates** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para10-ex1-pf1))
- Part: C | Type: example | Level: N/A
- Content: "/{version}/{namespace}/{resource}/{resource-id}/{sub-resource}/{sub-resource-id} /{version}/{resource}/{resource-id}/{sub-resource}/{sub-resource-id}"
- Tags: []
- Score: 0.8384
28. **Full Path with Namespace** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para10-ex1-pf1-pfl1))
- Part: C | Type: example | Level: N/A
- Content: "/{version}/{namespace}/{resource}/{resource-id}/{sub-resource}/{sub-resource-id}"
- Tags: []
- Score: 0.8376
29. **Version Heading** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-h2))
- Part: C | Type: heading | Level: 2
- Content: "1.5.2. Version"
- Tags: []
- Score: 0.8358
30. **Content-Type with Version Example** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para6-ex1-exl1))
- Part: C | Type: example | Level: N/A
- Content: "`Content-Type: application/json,version=1.2`"
- Tags: []
- Score: 0.8273
---
## Summary of Deployment Phase Research
### Mandatory Requirements Identified
1. **Agencies MUST NOT Include Minor Versions in API Paths** - When using URL-based versioning ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para6))
2. **External APIs MUST Be Well Documented** - Accurate and up-to-date guidance via catalogue ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para61))
### Strong Elevation Candidates (should→MUST)
1. **APIs Should Have Clear Version Indication** - So developers can ensure correct version ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para4))
2. **Header-Based Versioning Recommended** - With recognition that some infrastructure doesn't support it ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section5-para5))
3. **Version on Breaking Changes** - API should be versioned when changes are breaking ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para11))
4. **Old Versions Should Be Maintained** - Alongside new versions for appropriate transition period ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section6-para3)) - annotated as "arguably mandatory"
5. **API Stability Important** - Available and work consistently, early versions via pilots ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section6-para1)) - annotated "This uses the language of should but I think it's mandatory"
6. **Machine-Readable Specifications Should Be Provided** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para9)) - annotated as "Arguably should be mandatory"
7. **Version Control Beyond Resources** - Include all API artifacts in SCM ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para16))
8. **Response Should Indicate Version** - Using Content-Type or Location header ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section10-para10))
### Key Topics Covered
1. **Versioning Methodologies** - Header-based (recommended) and URL-based (viable alternative)
2. **When to Version** - Breaking changes vs non-breaking changes
3. **Version Formats** - /vN for URL, Accept header with wildcards
4. **API Gateway** - Definition, capabilities, role as policy enforcement point
5. **API Documentation** - Must be well-documented, accurate, up-to-date
6. **API Components** - Developer portal, API gateway, API manager
7. **Version Control** - All artifacts in SCM, not just resources
8. **Release Management** - Small changes, release often
9. **Agile Practices** - Iterative development, failing fast, frequent delivery
10. **Backwards Compatibility** - Minor changes must be backwards compatible
11. **Version Maintenance** - Maintain old versions during transition
12. **Developer Communication** - Forewarn of changes, identify all developers
### Notes for Drafting
- Two versioning methods acceptable, versioning itself is what's important
- Header-based versioning more RESTful but harder to implement
- URL-based versioning pragmatic alternative
- Breaking changes = major version (1.x to 2.0)
- Non-breaking changes = minor version (1.1 to 1.2)
- Legislative changes may force new versions and deprecation
- Well-managed APIs handle regular change
- API gateway has six key capabilities
- Configuration management for rebuild capability
- Agile practices suit API development