Good Practices 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: Good Practices Research
---
# Good Practices Research Results
**Phase**: Good Practice Content by Topic
**Total Searches**: 6
**Total Results**: ~117 results
**Date**: 2025-11-03
## Search Queries Executed
1. `semantic_search_filtered: tags=["good-practice"], query="API design principles"` (limit: 30, returned 27)
2. `semantic_search_filtered: tags=["good-practice"], query="API development best practices"` (limit: 30, returned 25)
3. `semantic_search_filtered: tags=["good-practice"], query="API security practices"` (limit: 30, returned 18)
4. `semantic_search_filtered: tags=["good-practice"], query="API testing quality"` (limit: 30, returned 15)
5. `semantic_search_filtered: tags=["good-practice"], query="API documentation standards"` (limit: 30, returned 19)
6. `semantic_search_filtered: tags=["good-practice"], query="API lifecycle operations"` (limit: 30, returned 13)
---
## Search 1: API Design Principles
**Query**: `semantic_search_filtered: tags=["good-practice"], query="API design principles"`
**Results**: 27
**Purpose**: Find all good practice recommendations related to API design principles
### Top Results
1. **Core design principles** - Score: 0.917
- Content: These are a set of principles that are considered good practice when designing, implementing and operating APIs. The New Zealand Government Digital Service Design Standard provides a wider perspective and set of principles that should also influence the design of APIs and the services they support. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-para1))
- Tags: should-or-may, good-practice, standards_review
- **Annotation**: "Links out to broader context in Digital Service Design Standard. Decision to be made about whether this is made mandatory - hard to see why GCDO wouldn't make this mandatory."
2. **Business principles for API development** - Score: 0.910
- Content: Principles — In order to incorporate all-of-government thinking into API development it is useful to have a set of business principles that should influence the way APIs are built and their usefulness over time. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section9-para3-8))
- Tags: good-practice, should-or-may, standards_review
3. **Design for the consumer** - Score: 0.878
- Content: 2.1. Design for the consumer APIs need to be developed with the consumer primarily in mind... ensuring a low barrier to entry so it is easy to start using the API providing sandbox APIs so application developers can try out APIs and develop in parallel being responsive to feedback and bug reports providing automated onboarding processes, as manual processes can limit take-up providing prototyping tools and support for development ensuring the funding cycle does not introduce a bottleneck for uptake within government selling the concept to the consumer early on so they create demand that industry needs to meet creating an atmosphere of competition in industry for take-up of the API creating a software development kit (SDK) to support an agency's APIs, including examples. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section1))
- Tags: to-review, good-practice, should-or-may, standards_review
- **Annotation**: "Solid argument that this block is more-or-less mandatory, or very tightly linked to essential upstream design processes. Ie, if agencies can't do this, should they be doing an API?"
4. **Business process analysis** - Score: 0.877
- Content: When designing an API, it is important to perform business process analysis to ensure that API development is business driven rather than technology driven. Technology-driven projects rarely meet customers' needs in the long run, so it is important to gain background in who could be using the API, and for what. As mentioned previously, co-design is fundamental to driving the right API development. To help identify potential partners to involve in the co-design, consider processes that: ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para23))
- Tags: definition, definitions, good-practice, should-or-may, must-or-shall, standards_review
- **Annotation**: "Process flow."
5. **Dogfooding principle** - Score: 0.877
- Content: 2.5. Dogfooding When building an API, there is always a danger of building the wrong thing in the wrong way for the wrong people. This is especially a risk in the absence of external developers driving or informing the development of the API. The simplest way to ensure an API is useful and consumable is to build the API as part of delivering a larger-scale internal business support system such as a web application... So, wherever feasible, design an API in consultation with application developers but build it in parallel with an accompanying integration of that API to ensure it is fit for purpose — in other words, build for inside use, then expose. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section5))
- Tags: good-practice, standards_review
6. **Design-driven development** - Score: 0.874
- Content: 2.2. Design-driven development This builds on the principle of 'Design for the consumer' and could also be phrased as 'specification-driven development' because the interface specification for the API is written first... The process of creating a specification before development forces the API developer to properly consider the purpose and content of the interface they are providing, before coding starts. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section2))
- Tags: good-practice, should-or-may, standards_review
- **Annotation**: "Process checklist."
7. **Co-design principle** - Score: 0.873
- Content: 2.3. Co-design This principle is the natural extension to both the 'Design for the consumer' and 'Design-driven development' principles and includes collaborating with the consuming application developer community when designing the interface... Application developers are one of the primary customers for the API and, as such, are a primary source of requirements. Working with application developers to define the requirements and to design the interface ensures the API will meet their needs. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section3))
- Tags: should-or-may, good-practice, standards_review
- **Annotation**: "Note that this refers out to the strategy for a digital public service."
8. **API granularity principle** - Score: 0.873
- Content: There is a question as to how fine-grained an API resource should be. APIs should be designed at the lowest practical level of granularity because this makes each service simpler and allows them to be combined in ways that suit the application developer. The key principle is to design services that can be re-used and combined in different ways, and not tie the application developer to a specific way of working or sequence of API consumption just because that is how it is configured or built in the backend. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para43))
- Tags: should-or-may, good-practice, standards_review
9. **API usability aimed at developers** - Score: 0.869
- Content: Application developers build the applications that consume your APIs. When designing an API, the usability or function of the API should be aimed at this group. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para5))
- Tags: should-or-may, good-practice, must-or-shall, standards_review
- **Annotation**: "Difficult to see how this is not mandatory."
10. **Informing application developers** - Score: 0.868
- Content: When designing an API, it is important to inform all potential application developers as to the thinking behind the API, including the resources to be exposed, the granularity of access, and capabilities to be offered. This can include roadmaps to indicate the planned evolution of an API so that developers are pre-warned and have time to prepare for changes. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section1-para2))
- Tags: should-or-may, good-practice, standards_review
- **Annotation**: "Should be mandatory I think."
### Key Design Principles Identified
**Mandatory Design Principles (from annotations and content):**
1. **Design for the consumer** - APIs developed with consumer primarily in mind
2. **Business process analysis** - Ensure business-driven vs. technology-driven
3. **API usability aimed at developers** - Function should be aimed at application developers
4. **Digital Service Design Standard alignment** - Should influence API design
**Strongly Recommended Principles:**
1. **Design-driven development** - Interface specification written first
2. **Co-design** - Collaborate with consuming application developer community
3. **Dogfooding** - Build as part of larger internal system, use in production
4. **Lowest practical granularity** - APIs designed to be re-usable and combinable
5. **Inform developers** - Provide thinking, roadmaps, evolution plans
6. **Simple and well-described** - APIs and onboarding processes easy to understand
7. **Agile/iterative approach** - Get early releases out, adapt based on feedback
**Examples of Design for Consumer in Action:**
- Ensuring low barrier to entry
- Providing sandbox APIs
- Being responsive to feedback and bug reports
- Providing automated onboarding processes
- Providing prototyping tools and support
- Creating Software Development Kit (SDK) with examples
- Not predicting how consumer will interact (leave application developer to innovate)
---
## Search 2: API Development Best Practices
**Query**: `semantic_search_filtered: tags=["good-practice"], query="API development best practices"`
**Results**: 25
**Purpose**: Find good practice recommendations for API development processes
### Top Results
1. **Dogfooding** - Score: 0.890
- Content: 2.5. Dogfooding When building an API, there is always a danger of building the wrong thing in the wrong way for the wrong people... The best way to design an API is in collaboration with the potential consuming application developers. The best way to understand and address the weaknesses in an API's design and implementation is to use it in a production system. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section5))
- Tags: good-practice, standards_review
2. **Collaborative, flexible, adaptive development** - Score: 0.886
- Content: APIs need to be developed in a collaborative, flexible and adaptive way. Once the API interface specification is agreed, it is more important to get something developed, however small, and get that published for application developers than to try to build a complete API product for release. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para2))
- Tags: good-practice, should-or-may, standards_review
3. **Design for the consumer** - Score: 0.884
- Content: [Full section on designing APIs with consumer primarily in mind, including low barrier to entry, sandbox APIs, responsive to feedback, automated onboarding, prototyping tools, SDK with examples] ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section1))
- Tags: to-review, good-practice, should-or-may, standards_review
- **Annotation**: "Solid argument that this block is more-or-less mandatory..."
4. **Business principles** - Score: 0.882
- Content: Principles — In order to incorporate all-of-government thinking into API development it is useful to have a set of business principles that should influence the way APIs are built and their usefulness over time. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section9-para3-8))
- Tags: good-practice, should-or-may, standards_review
5. **When an API may be more appropriate** - Score: 0.880
- Content: Situations where an API may be more appropriate are when: ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para5))
- Tags: good-practice, standards_review
6. **Co-design with developers** - Score: 0.880
- Content: Ideally, the API services should be designed in collaboration with application developers to ensure the right product is developed to support diverse business processes across a broad set of consuming applications. It is best if API development can be performed in coordination with application developers who are producing consuming applications. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section1-para3))
- Tags: good-practice, standards_review
7. **API usability aimed at developers** - Score: 0.880
- Content: Application developers build the applications that consume your APIs. When designing an API, the usability or function of the API should be aimed at this group. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para5))
- Tags: should-or-may, good-practice, must-or-shall, standards_review
- **Annotation**: "Difficult to see how this is not mandatory."
8. **Application developers invest heavily** - Score: 0.879
- Content: Application developers will invest heavily in using your API. They will invest in learning the design and behaviour of your API, in developing and testing around your API and may even invest in developing an entire business model on your API. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para2))
- Tags: good-practice, standards_review
9. **Needs and drivers for APIs** - Score: 0.879
- Content: 1.5. Needs and drivers So why build an API? In what situation is an API the right thing to develop? [Lists 10 drivers including collaborative service delivery, cloud services, open data, channel shift, etc.] ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section5))
- Tags: good-practice, standards_review
- **Annotation**: "Purpose of an API - process checklist tool."
10. **API stability and pilot versions** - Score: 0.878
- 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. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section6-para1))
- Tags: good-practice, should-or-may, must-or-shall, standards_review
- **Annotation**: "This uses the language of should but I think it's mandatory."
### Key Development Best Practices
**Development Process:**
- Collaborative, flexible, and adaptive way
- Get something small developed and published rather than complete product
- Build in parallel with consuming application integration (dogfooding)
- Perform business process analysis (business-driven vs. technology-driven)
- Focus on extracting true requirements through functional analysis
**Developer Engagement:**
- Co-design with application developers
- Work with developers to define requirements and design interface
- Early versions available via pilots or developer portals
- Simple to understand and well-described APIs and onboarding
**Development Approach:**
- Design API in consultation with developers
- Build in parallel with integration to ensure fit for purpose
- Make small changes and release often
- Agile/iterative approach with early partially complete releases
- Get feedback incorporated early
**Risks to Avoid:**
- Building the wrong thing in the wrong way for the wrong people
- Technology-driven projects (rarely meet customer needs)
- Predicting how consumer will interact (leave developer to innovate)
- Getting bogged down in variety of proposed solutions from each developer
---
## Search 3: API Security Practices
**Query**: `semantic_search_filtered: tags=["good-practice"], query="API security practices"`
**Results**: 18
**Purpose**: Find good practice recommendations for API security
### Top Results
1. **Security component for every API** - Score: 0.908
- Content: Every API will have a security component. It is important to recognise that this is not only authentication and authorisation for access to an API, it also includes threat protection (Distributed Denial of Service (DDoS), Structured Query Language (SQL) Injection, Cross Site Scripting, and so on) as well as availability and Quality of Service (QoS). When designing and developing APIs it is often cost effective to create a common framework that handles security for all APIs. See Part B: API security 2022 for more details. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para15))
- Tags: definition, definitions, must-or-shall, should-or-may, good-practice, standards_review
2. **API security reference architecture** - Score: 0.890
- Content: This section describes an API security reference architecture and its component parts to inform the construction of an API security framework. It is important to note that REST, gRPC, GraphQL and AsyncAPI are different architectural models for building synchronous and asynchronous APIs that can leverage the security controls (for example, OAuth 2.0 and OpenID Connect) defined in these guidelines, but they all have their own intrinsic security models (for example, throttling consideration in GraphQL) which are not covered in these guidelines. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para1))
- Tags: reference-examples-apis, substantive_review, good-practice, must-or-shall, standards_review
- **Annotation**: "Contextual security requirements depending on architecture adopted."
3. **Trusted subsystem pattern** - Score: 0.886
- Content: API security is provided by the application (web) server acting as a trusted subsystem with TLS links to the backend API server. The application / web server invokes the backend and provides the required user ID information, which can be in the form of a session token. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section2-para4))
- Tags: good-practice, standards_review
4. **Threat mitigation and secure coding** - Score: 0.884
- Content: As mentioned in section 1.3. Risks, there are various types of risk that impact APIs. This includes threats to availability as well as confidentiality and integrity. Many threats can be mitigated as indicated in section 1.3.1. Mitigation approach and good secure coding practices using OWASP guidelines. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part4-section2-para6))
- Tags: definition, definitions, links-out-external, substantive_review, good-practice, standards_review
5. **API and web standards** - Score: 0.882
- Content: In addition to the security standards captured in Part B: API security 2022, table 7 captures (current) API and web standards that should be considered as part of any API strategy. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part7-para2))
- Tags: should-or-may, good-practice, standards_review
6. **API gateway security capabilities** - Score: 0.879
- Content: security — offering authentication and authorisation services. Using threat protection capability to protect backend systems against common vector attacks such as SQL injection, Cross Site Scripting and Cross Site Forgery. The API gateway is essentially the Policy Enforcement Point (PEP) ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para5-1))
- Tags: definition, definitions, good-practice, standards_review
7. **API keys recommendation** - Score: 0.877
- Content: **Note:** API keys are **recommended** as they provide a level of security to public APIs that can help protect sites from screen scraping or provide the required information to throttle, or possibly bill, access to data. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section3-para9-ex1))
- Tags: should-or-may, good-practice, standards_review
8. **Authentication requirement** - Score: 0.875
- Content: When securing APIs, authentication is required to identify the consumers and / or consuming applications that want to access or consume an API. Authentication enables the API provider to identify all consumers of an API and to confirm that the consumer requesting access is who they say they are. This does not automatically authorise them to access the APIs or the underlying resources. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-para1))
- Tags: must-or-shall, good-practice, standards_review
9. **Privacy and sensitivity awareness** - Score: 0.874
- Content: APIs are used extensively for passing information on, so it is important to consider the information privacy and sensitivity aspects of data being passed to and from APIs to ensure that data is protected adequately. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section7-para1))
- Tags: should-or-may, good-practice, must-or-shall, standards_review
10. **Authentication techniques figure** - Score: 0.873
- Content: Figure 13 lists the following authentication techniques that can be used to secure APIs and where they are used: Developer authentication — used to log in to the API portal; Anonymous — not recommended to use; Multi-factor authentication: User name and password — not recommended for public facing APIs, useful in development / training environments; API keys — recommended to use for all APIs, used for application authentication (not human); Certificates — used for: consuming application (B2B only) to API gateway, OAuth 2.0 client to authorisation server, API gateway to backend systems; OAuth2 and security tokens — recommended to use for internal and external production APIs; OpenID Connect — recommended to use where there is an OpenID Connect provider. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part3-section1-fig13-det1))
- Tags: figures, substantive_review, should-or-may, good-practice, standards_review
### Key Security Best Practices
**Security Framework:**
- Every API will have a security component (authentication, authorization, threat protection, availability, QoS)
- Common framework that handles security for all APIs (cost effective)
- API security reference architecture to inform construction
- Different architectural models (REST, gRPC, GraphQL, AsyncAPI) have intrinsic security models
**Authentication and Authorization:**
- Authentication is required to identify consumers/applications
- API keys recommended for all APIs
- OAuth2 and security tokens recommended for internal and external production APIs
- OpenID Connect recommended where provider exists
- Multi-factor authentication where appropriate
- Certificates for B2B, OAuth 2.0 clients, backend systems
**Threat Protection:**
- Threat protection capabilities (DDoS, SQL Injection, Cross Site Scripting)
- API gateway as Policy Enforcement Point (PEP)
- Common vector attack protection
- OWASP guidelines for secure coding practices
- Throttling and schema validation
- Should not replace other defences, but augment them
**Privacy and Sensitivity:**
- Consider information privacy and sensitivity aspects
- Privacy impact assessment appropriate for API development stages
- Security risk assessment appropriate for development stages
- Regular assessments especially early in concept phase
- Particular attention for private, personal information
**Authorization Code Grant:**
- Initial consideration for any API security framework should be authorization code grant type
---
## Search 4: API Testing and Quality
**Query**: `semantic_search_filtered: tags=["good-practice"], query="API testing quality"`
**Results**: 15
**Purpose**: Find good practice recommendations for testing and quality assurance
### Top Results
1. **Issue reporting** - Score: 0.861
- Content: reporting issues with the API. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section3-para8-4))
- Tags: good-practice, standards_review
2. **Testing in SDLC** - Score: 0.853
- Content: Tests can be written against the interface specification quite early on in the development process by developing just enough API code to enable the test to be run (stubs). The tests can then be incorporated into the automated build process, giving early warning of regression test failures. API code should not be able to progress through Software Development Life Cycle (SDLC) environments until successful test execution. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para42))
- Tags: must-or-shall, should-or-may, good-practice, standards_review
- **Annotation**: "Test suites"
3. **API stability and pilot testing** - Score: 0.845
- 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. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section6-para1))
- Tags: good-practice, should-or-may, must-or-shall, standards_review
- **Annotation**: "This uses the language of should but I think it's mandatory."
4. **Threat protection and QoS** - Score: 0.834
- Content: To protect an agency's resources, the API component should perform threat protection and quality of service (QoS) functions. This could be in the form of 'throttling' requests, schema validation and common vector attack protection (Structured Query Language (SQL) injection, Cross Site Scripting). This functionality should not be seen as a replacement for other defences, but an augmentation to those defences. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para11))
- Tags: definition, definitions, should-or-may, must-or-shall, good-practice, standards_review
- **Annotation**: "Seems mandatory."
5. **Continual service improvement** - Score: 0.831
- Content: 4.4. Continual service improvement It is not sufficient to release an API and let service operation keep it running. There is also a need to ensure that APIs are running optimally and can adapt to changing demand over time... [Details on analytics, performance metrics, API availability monitoring] ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section4))
- Tags: must-or-shall, good-practice, should-or-may, standards_review
### Key Testing and Quality Practices
**Testing Approach:**
- Tests written against interface specification early in development
- Develop stubs (just enough API code to enable test to run)
- Tests incorporated into automated build process
- Early warning of regression test failures
- **API code should not progress through SDLC until successful test execution**
**Quality of Service:**
- Threat protection and QoS functions
- Throttling requests
- Schema validation
- Common vector attack protection (SQL injection, Cross Site Scripting)
- Not a replacement for other defences, but augmentation
**Pilot Testing:**
- Early versions available via pilots or developer portals
- Application developers can work APIs and identify instability
- Before API goes into production
**API Stability:**
- APIs have stability (available and work consistently)
- Support velocity of change acceptable to application developers
- Early releases tested and stable to not impede uptake
**Continual Improvement:**
- Not sufficient to release and let service operation keep it running
- Ensure APIs running optimally and adapt to changing demand
- Gather analytical data (take-up metrics, performance, errors)
- Monitor usage and respond dynamically to increases in demand
**Documentation:**
- External API must be well documented
- Provide accurate and up-to-date guidance via catalogue
- Machine-readable specifications should be provided
---
## Search 5: API Documentation Standards
**Query**: `semantic_search_filtered: tags=["good-practice"], query="API documentation standards"`
**Results**: 19
**Purpose**: Find good practice recommendations for API documentation
### Top Results
1. **API interface specification** - Score: 0.880
- 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 for details. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para9))
- Tags: definition, definitions, reference-examples-apis, substantive_review, should-or-may, good-practice, must-or-shall, standards_review
- **Annotation**: "Arguably should be mandatory."
2. **External API documentation requirement** - Score: 0.877
- 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. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para61))
- Tags: definition, definitions, catalogue, substantive_review, should-or-may, must-or-shall, good-practice, standards_review
- **Annotation**: "documentation"
3. **API and web standards** - Score: 0.873
- Content: In addition to the security standards captured in Part B: API security 2022, table 7 captures (current) API and web standards that should be considered as part of any API strategy. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part7-para2))
- Tags: should-or-may, good-practice, standards_review
4. **Collaborative development** - Score: 0.868
- Content: APIs need to be developed in a collaborative, flexible and adaptive way. Once the API interface specification is agreed, it is more important to get something developed, however small, and get that published for application developers than to try to build a complete API product for release. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para2))
- Tags: good-practice, should-or-may, standards_review
5. **API categories table** - Score: 0.865
- Content: Table 1: Common categories of API [Lists Internal API, External API, Partner API, Public or open API with descriptions] ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section2-para2-tb1))
- Tags: definition, definitions, good-practice, standards_review
6. **Digital Service Design Standard** - Score: 0.864
- Content: These are a set of principles that are considered good practice when designing, implementing and operating APIs. The New Zealand Government Digital Service Design Standard provides a wider perspective and set of principles that should also influence the design of APIs and the services they support. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-para1))
- Tags: should-or-may, good-practice, standards_review
- **Annotation**: "Links out to broader context in Digital Service Design Standard. Decision to be made about whether this is made mandatory - hard to see why GCDO wouldn't make this mandatory."
### Key Documentation Best Practices
**Interface Specification:**
- Technical description and reference model for an API
- Used by application developers to understand technical aspects
- Should be provided in machine-readable format
- Arguably should be mandatory
**Documentation Requirements:**
- External API must be well documented
- Provide accurate and up-to-date guidance via catalogue
- Primary discoverer is the developer
- API definition published to API catalogue
**Specification Design:**
- Interface specification designed in advance of developing API
- Act of working out specification helps think through all issues
- Helps consuming application developers review capabilities before they start
- Can be handled as separate entity, is version controllable
- Should be possible to use as main API documentation or reference
**Documentation Content:**
- Clear definition of what API offers
- How API resources are to be accessed
- Inform developers of thinking behind API
- Resources to be exposed
- Granularity of access
- Capabilities to be offered
- Roadmaps to indicate planned evolution
**Component Responsibilities:**
- API component responsible for maintaining interface specifications
- Publishing specifications to interface specification component
**Publication and Discovery:**
- Published API catalogue needs to be application developer focused
- Primary point of discovery is the application developer
- Well documented to encourage take-up
- API developer portal offers discovery capabilities
---
## Search 6: API Lifecycle Operations
**Query**: `semantic_search_filtered: tags=["good-practice"], query="API lifecycle operations"`
**Results**: 13
**Purpose**: Find good practice recommendations for lifecycle management and operations
### Top Results
1. **API service lifecycle management diagram** - Score: 0.899
- Content:  ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-fig1-src1))
- Tags: good-practice, standards_review
2. **Full lifecycle diagram with description** - Score: 0.881
- Content: Figure 7 is a circular flow diagram that illustrates the service life cycle management of an API. An outer circle surrounds the entire diagram and represents continual service improvement. At the centre is a circle representing service strategy. Between these 2 layers are the following 3 areas that flow from 1 to the other: Service design — consumer management, service level management and API design; Service transition — internal development and testing, API catalogue, API release management and life cycle / change management; Service operation — access management, consumer support, incident / event management and API management. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-fig1))
- Tags: good-practice, standards_review
3. **Performance analytics and SLAs** - Score: 0.877
- Content: Performance analytics enable you to ensure your APIs are meeting SLAs and other contractual obligations. Using analytics to gain insight into API usage should help in making future investment decisions. See 4. Life cycle management for more details. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para26))
- Tags: definition, definitions, should-or-may, good-practice, standards_review
- **Annotation**: "Framed around future use and decision-making so hard to make it mandatory now, but it seems like having some analytics should be a requirement of the standard."
4. **API components description** - Score: 0.868
- Content: 5.1. API components The following are definitions of components that provide API development support capabilities... [Describes API developer portal, API gateway, API manager with detailed capabilities] ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1))
- Tags: good-practice, standards_review
5. **Lifecycle diagram detailed description** - Score: 0.861
- Content: [Detailed description of Figure 7 showing circular flow: continual service improvement surrounding service strategy, with service design/transition/operation flowing between] ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-fig1-det1))
- Tags: good-practice, standards_review
6. **Release management** - Score: 0.855
- Content: Release management is an important aspect of API transition. The aim with API development is to make small changes and release often. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para6))
- Tags: definition, definitions, good-practice, should-or-may, standards_review
7. **Using operational data** - Score: 0.849
- Content: It is important not just to monitor and gather operational data about running APIs, but also to use that information to improve API offerings. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section4-para5))
- Tags: should-or-may, good-practice, standards_review
### Key Lifecycle and Operations Best Practices
**Service Lifecycle Model:**
- Continual service improvement (outer layer surrounding all)
- Service strategy (center)
- Service design: consumer management, service level management, API design
- Service transition: internal development and testing, API catalogue, API release management, life cycle/change management
- Service operation: access management, consumer support, incident/event management, API management
**API Manager Capabilities:**
- Life cycle management — managing full life cycle from initial publication to destruction
- Main capabilities support: planning and design, implementation, basic and advanced deployment and running, versioning and retirement
- Applying policies to individual APIs
- Helping to onboard consuming applications
**Release Management:**
- Important aspect of API transition
- Aim is to make small changes and release often
- Collaborative, flexible, and adaptive way
**Operational Monitoring:**
- Not sufficient to release API and let service operation keep it running
- Monitor and gather operational data
- Use information to improve API offerings
- Transaction-throughput monitoring to identify bottlenecks or overloaded APIs
- Ramp up availability to meet demand
**Analytics:**
- Performance analytics ensure APIs meeting SLAs and contractual obligations
- Gain insight into API usage for future investment decisions
- Capture take-up metrics, end-user analytics, API usage, performance
- Error rate, throughput, response time, transaction speed, backend performance, cache performance
- Demonstrate Return on Investment (ROI)
**Well-Managed APIs:**
- Handle regular change as take-up increases
- Good version control capability
- Forewarn application developers of changes, failures, outages
- Important to identify all application developers, even for public APIs
**API Categorization for Governance:**
- System APIs, Process APIs, Experience APIs
- Categories provide way of grouping based on level of governance needed
- Different frequency of change, effort of change, potential impact
---
## Cross-Cutting Good Practices
### Practices Appearing in Multiple Searches
**Design Principles:**
- Design for the consumer (4 searches)
- Design-driven development / specification-first (4 searches)
- Co-design with application developers (3 searches)
- Business process analysis (3 searches)
- Dogfooding (3 searches)
**Development:**
- Collaborative, flexible, adaptive (3 searches)
- Small changes, release often (3 searches)
- Tests in automated build process (2 searches)
- Early versions via pilots/sandboxes (2 searches)
**Documentation:**
- Interface specification machine-readable (3 searches)
- External APIs well documented (3 searches)
- API catalogue publication (2 searches)
**Security:**
- Common security framework for all APIs (2 searches)
- Authentication required (2 searches)
- Threat protection and QoS (2 searches)
**Lifecycle:**
- Continual service improvement (2 searches)
- Analytics for API usage and performance (2 searches)
- Version control and change communication (2 searches)
---
## Elevation Candidates (Should→MUST)
Based on annotations and content analysis, the following good practices are strong candidates for elevation to mandatory requirements:
### Design Phase
1. **Design for the consumer** - "Solid argument that this block is more-or-less mandatory"
2. **API usability aimed at developers** - "Difficult to see how this is not mandatory"
3. **Business process analysis** - Ensure business-driven development
4. **Inform developers of API thinking and roadmaps** - "Should be mandatory I think"
5. **Digital Service Design Standard alignment** - "Hard to see why GCDO wouldn't make this mandatory"
### Development Phase
1. **Design-driven development** - "Arguably should be mandatory"
2. **Testing in SDLC** - "API code should not be able to progress through SDLC environments until successful test execution"
3. **API stability and pilot testing** - "This uses the language of should but I think it's mandatory"
### Security Phase
1. **Privacy impact assessment** - "Hard to see how this is not mandatory"
2. **Threat protection and QoS** - "Seems mandatory"
### Deployment Phase
1. **External API documentation** - External API must be well documented
2. **Machine-readable specifications** - "Arguably should be mandatory"
### Operations Phase
1. **Performance analytics for SLAs** - "Seems like having some analytics should be a requirement"
---
## Good Practice Distribution by Part
- **Part A**: ~85 results (majority - principles, lifecycle, components)
- **Part C**: ~25 results (development, design, testing)
- **Part B**: ~7 results (security practices)
**Note**: Part A dominates good practice content, with comprehensive guidance on principles, lifecycle management, and API components.
---
## Key Statistics
- **27 design principle results** - foundational guidance
- **25 development best practice results** - process and approach
- **18 security practice results** - framework and protection
- **15 testing/quality results** - assurance practices
- **19 documentation results** - specification and publication
- **13 lifecycle/operations results** - management approach
**Total unique good practice recommendations**: ~117 results across all lifecycle phases
---
## Notes for Drafting Sections
### Use in Design Phase Section
- All 8 design principles (Part A, section 2)
- Business process analysis
- Co-design approach
- API categorization (System, Process, Experience)
### Use in Development Phase Section
- Collaborative, flexible, adaptive development
- Specification-first approach
- Testing in SDLC (automated, stubs, regression)
- Pilot/sandbox environments
- Small changes, release often
### Use in Security Phase Section
- Common security framework
- Threat protection and QoS
- Authentication requirement
- Privacy impact assessment
- OWASP guidelines reference
### Use in Deployment Phase Section
- Interface specification (machine-readable)
- API catalogue publication
- Documentation requirements
- Release management
### Use in Operations Phase Section
- Service lifecycle model (Figure 7)
- Continual service improvement
- Analytics and performance monitoring
- Version control and change communication
- API manager capabilities
---
## Total Research Phase Complete
**Research files created**: 8
**Total search queries executed**: 43
**Total results captured**: ~1,000+ results
**Next phase**: Begin drafting The New Zealand API Standard document