Patterns 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: Patterns Research
---
# Patterns Research Results
**Phase**: API Patterns and Examples
**Total Searches**: 3
**Total Results**: ~82 results
**Date**: 2025-11-03
## Search Queries Executed
1. `semantic_search_filtered: tags=["patterns"], query="authentication authorization patterns"` (limit: 50, returned 30)
2. `semantic_search_filtered: tags=["reference-examples-apis"], query="API examples code samples"` (limit: 50, returned 2)
3. `semantic_search: "API design patterns implementation examples"` (limit: 50)
---
## Search 1: Authentication and Authorization Patterns
**Query**: `semantic_search_filtered: tags=["patterns"], query="authentication authorization patterns"`
**Results**: 30
**Purpose**: Find all authentication and authorization patterns with pattern tags
### Top Results
1. **Pattern quick reference** - Score: 0.913
- Content: The following provides a quick reference to identify the most appropriate authentication and authorisation model to use for the patterns defined. The models are explained in detail in subsequent sections. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-para1))
- Tags: patterns, substantive_review
2. **Common pattern principle** - Score: 0.877
- Content: Use a common authentication and authorisation pattern, preferably based on existing security components: avoid creating a bespoke solution for each API. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para10-3))
- Tags: patterns, substantive_review
3. **Pattern 3: Anonymous consuming application** - Score: 0.864
- Content: The most appropriate authentication and authorisation model is API keys. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-det3))
- Tags: patterns, substantive_review
4. **Pattern 1 recommendation** - Score: 0.855
- Content: For [pattern 1](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section1): internal use only, the authorisation code grant type is recommended, where practical. Otherwise, it may be appropriate to leverage the provider agency's existing internal authentication and authorisation providers. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part2-section9-para2-5))
- Tags: patterns, substantive_review, should-or-may, standards_review
### Eight Authentication/Authorization Patterns Identified
#### Pattern 1: Internal Use Only
- **Location**: Part B, section 2.1
- **Scenario**: API developed for internal use only by agency applications or systems
- **Recommended Auth Model**:
- Authorization code grant type (where practical)
- Or leverage existing internal authentication/authorization providers
- **Figure**: Figure 5
#### Pattern 2: Identifying an Application Developer
- **Location**: Part B, section 2.2
- **Scenario**: Application developer authentication to API developer portal for registration
- **Recommended Auth Model**: API gateway proprietary
- **Figure**: Figure 6
- **Tags**: patterns, substantive_review, good-practice, to-review, standards_review
- **Annotation**: "Some of this feels very elementary - almost as if it's written for a developer who has never developed an API before. Is that who these standards are for?"
#### Pattern 3: Anonymous Consuming Application
- **Location**: Part B, section 2.3
- **Scenario**: API provider does not need to know which consuming applications are using their APIs
- **Recommended Auth Model**: API keys
- **Figure**: Figure 7
#### Pattern 4: Identifying a Consuming Application
- **Location**: Part B, section 2.4
- **Scenario**: API provider needs to know which consuming applications are using their APIs (for communication, logging, analytics)
- **Recommended Auth Models**:
- API keys (Recommended)
- API gateway proprietary
- **Figure**: Figure 8
- **Tags**: patterns, substantive_review, should-or-may, good-practice, standards_review
#### Pattern 5: Authorising a System-to-System Interaction (B2B)
- **Location**: Part B, section 2.5
- **Scenario**: API used for information sharing or integration with external system (partner agency)
- **Recommended Auth Models**:
- Mutual TLS (certificates)
- API keys
- OAuth 2.0 client credentials grant (without OpenID Connect, without PKCE) - Recommended
- API gateway proprietary
- **Figure**: Figure 9
#### Pattern 6: Authorising a Consuming Application
- **Location**: Part B, section 2.6
- **Scenario**: Different external consuming applications granted different levels of access to resources (not dependent on customer using application)
- **Recommended Auth Models**:
- API keys
- OAuth 2.0 client credentials grant (without OpenID Connect, without PKCE) - Recommended
- API gateway proprietary
- **Figure**: Figure 10
- **Example**: Application A pays fee, gets different QoS than Application B
- **Tags**: patterns, substantive_review, good-practice, should-or-may, standards_review
#### Pattern 7: Authorising a Customer (Delegated Authority)
- **Location**: Part B, section 2.7
- **Scenario**: External consuming applications granted different access to resources depending on which customer is using the application
- **Recommended Auth Models**:
- API keys
- OAuth 2.0 grant types:
- Resource owner password credentials (without OpenID Connect, without PKCE)
- Authorization code (without OpenID Connect, without PKCE) - Recommended
- Authorization code (without OpenID Connect, with PKCE) - Recommended
- Authorization code (with OpenID Connect, without PKCE) - Recommended
- Authorization code (with OpenID Connect, with PKCE) - Recommended
- CIBA (with OpenID Connect, without PKCE) - Recommended
- OpenID Connect Hybrid flows
- API gateway proprietary
- **Figure**: Figure 11
- **Example**: Learner authorizes mobile application to retrieve their own record of achievement
- **Tags**: patterns, substantive_review, good-practice, should-or-may, standards_review
#### Pattern 8: Decoupled Flow — Client Initiated Backchannel Authentication (CIBA)
- **Location**: Part B, section 2.8
- **Scenario**: Authentication and consent process delegated to authentication device of end user via out-of-band mechanism
- **Recommended Auth Model**:
- OAuth 2.0 CIBA grant type (with OpenID Connect, without PKCE) - Recommended
- **Figure**: Figure 12
- **Tags**: patterns, substantive_review, should-or-may, good-practice, standards_review
### Key Findings
**Mandatory Principle:**
- Different API usage patterns require different authentication and authorization models
- **Avoid bespoke solutions** - Use common authentication/authorization pattern based on existing security components
**Pattern Recommendations Summary:**
- Pattern 1: Authorization code grant OR existing internal auth
- Pattern 2: API gateway proprietary
- Pattern 3: API keys
- Pattern 4: API keys (Recommended) OR API gateway proprietary
- Pattern 5: OAuth 2.0 client credentials (Recommended), mutual TLS, API keys, or gateway proprietary
- Pattern 6: OAuth 2.0 client credentials (Recommended), API keys, or gateway proprietary
- Pattern 7: OAuth 2.0 authorization code with various options (Recommended), API keys, or gateway proprietary
- Pattern 8: OAuth 2.0 CIBA (Recommended)
**For Pattern 6 (additional note):**
- Client credentials grant type is recommended
- API keys model can be used instead
- Tags: patterns, substantive_review, should-or-may, good-practice, standards_review
---
## Search 2: API Examples and Code Samples
**Query**: `semantic_search_filtered: tags=["reference-examples-apis"], query="API examples code samples"`
**Results**: 2
**Purpose**: Find code examples and samples tagged as reference examples
### Results
1. **Discovery of APIs** - Score: 0.851
- Content: * discovery of APIs ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para6-tb1-tr1-td2-l2))
- Tags: definition, definitions, reference-examples-apis, substantive_review
2. **Best practice reference** - Score: 0.849
- Content: capture API best practice for reference by the API development community, indicating where commonality is required, and which areas allow for more flexibility ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section6-para1-4))
- Tags: reference-examples-apis, substantive_review
### Key Finding
**Very Limited Code Examples:**
- Only 2 results with "reference-examples-apis" tag
- Guidelines are primarily conceptual/architectural rather than code-focused
- Actual code examples are likely embedded in other sections without this specific tag
**Need to Look Elsewhere for Examples:**
- Part C, section 5: "Appendix A — Examples" likely contains OpenAPI/AsyncAPI specifications
- Part C has sections on API interface specification examples
- Search 3 results should provide more design pattern examples
---
## Search 3: API Design Patterns and Implementation Examples
**Query**: `semantic_search: "API design patterns implementation examples"`
**Results**: 50
**Purpose**: Broader search for design patterns and implementation examples
### Top Results
1. **Style and pattern guidelines** - Score: 0.899
- Content: style and pattern guidelines — standardising API design ensures APIs remain consistent and improve usability ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part2-para3-2))
- Tags: definition, definitions, patterns, reference-examples-apis, substantive_review
2. **API design principles** - Score: 0.892
- Content: 1.2.3. API design principles ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h3))
3. **API design section** - Score: 0.885
- Content: 1.2. API design ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-title))
4. **API design and development** - Score: 0.879
- Content: 1. API design and development ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-title))
5. **Designing an API** - Score: 0.879
- Content: 1.2.4. Designing an API ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h7))
6. **API design (Part A)** - Score: 0.877
- Content: 4.1.3. API design ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section1-h3))
7. **Examples in developer portal** - Score: 0.877
- Content: examples — offering example code and sample applications to illustrate the functionality of the API ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part5-section1-para3-4))
- Tags: definition, definitions
### Key Design Patterns and Principles
**Design-Driven Development:**
- Interface specification written first (Part A, section 2.2)
- Forces proper consideration before coding starts
- Allows application developers to assess if API meets needs
- Tags: good-practice, should-or-may, must-or-shall, standards_review
- **Annotation**: "Arguably should be mandatory."
**Design for the Consumer (Part A, section 2.1):**
- APIs developed with consumer primarily in mind
- Low barrier to entry
- Provide sandbox APIs
- Responsive to feedback
- Automated onboarding
- Prototyping tools
- Software Development Kit (SDK) with examples
- 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."
**Co-Design (Part A, section 2.3):**
- Collaborate with consuming application developer community
- Work together with government and business
- Application developers are primary source of requirements
- Agile/iterative approach
- Get early partially complete releases out
- Try, then adapt
- Tags: should-or-may, good-practice, standards_review
- **Annotation**: "Note that this refers out to the strategy for a digital public service."
**Dogfooding (Part A, section 2.5):**
- Build API as part of larger-scale internal business support system
- Use API in production system to understand weaknesses
- Build for inside use, then expose
- Design in consultation, build in parallel with integration
- Tags: good-practice, standards_review
**Business Process Analysis:**
- Ensure API development is business driven, not technology driven
- Identify potential co-design partners
- Tags: definition, definitions, good-practice, should-or-may, must-or-shall, standards_review
- **Annotation**: "Process flow."
### Architectural and Deployment Patterns
**Table 2: Architectural and deployment patterns** (Part C, section 1.3):
1. **Microservices**
- Reference: MartinFowler.com
2. **API Management**
- Reference: Nordic APIs - Understanding API management, API gateway, and API manager
3. **Observability**
- References: MartinFowler.com, O'Reilly
4. **API Publication/Discovery**
- Reference: API Evangelist
5. **Hybrid Deployments**
- Reference: Nordic APIs - Multi-cloud API approach
6. **Service Mesh**
- References: Nordic APIs, O'Reilly
### Implementation Guidance
**When Building APIs (Part C, section 1.2.4):**
- Design-driven approach MUST be taken
- Tags: definition, definitions, must-or-shall, standards_review
- **Annotation**: "This could easily be in a non-technical section."
**Good API Designs:**
- Attract more developers
- Bad designs drive away developers and drive up costs (support, maintenance, operating)
**Representation Layer:**
- Interface specification fully describes API
- Should be easy to consume
- Tags: definition, definitions, good-practice, should-or-may, standards_review
### OAuth 2.0 Implementation Patterns
**Section Reference**: Part B, section 3.3
- **Title**: Basic OAuth 2.0 implementation patterns
### Security Design Principles
**Section Reference**: Part B, section 1.5.1
- **Title**: API security design principles
---
## Appendix References
### Appendix A: Authentication Patterns
**Primary Source**: Part B, section 2 (all 8 patterns)
- Comprehensive descriptions with figures
- Authentication/authorization model recommendations
- Usage scenarios
- Quick reference guide (section 2.9)
### Appendix B: API Specification Examples
**Primary Source**: Part C, section 5 - "Appendix A — Examples"
- Note: Despite being called "Appendix A" in Part C, this should map to Appendix B in our standard
**Figures 5-8 mentioned** (Part C, para 5.1):
- Examples of agency API interface
- Likely includes OpenAPI/AsyncAPI specifications
**Specific Example Nodes Found:**
- Example Agency API title references
- API specification examples with OpenAPI format
### Additional Pattern Resources
**Part C, section 1.3**: Architectural and deployment patterns table
- Contains external references to industry best practices
- Covers microservices, API management, observability, service mesh, etc.
---
## Cross-References to Other Research Files
**Related to Security Phase:**
- All 8 authentication/authorization patterns
- OAuth 2.0 implementation patterns
- API keys usage
- Mutual TLS
- OpenID Connect
**Related to Design Phase:**
- Design-driven development
- Design for the consumer
- Co-design principle
- Dogfooding
- Business process analysis
**Related to Development Phase:**
- Interface specification (OpenAPI, AsyncAPI)
- REST API design patterns
- Good API design principles
**Related to Deployment Phase:**
- API gateway patterns
- Hybrid deployment patterns
- Service mesh
**Related to Operations Phase:**
- Pattern 4 (identifying consuming apps for logging/analytics)
- Monitoring and observability patterns
---
## Notes for Drafting Appendices
### Appendix A: Authentication Patterns
**Structure:**
1. **Introduction**
- Explain that different API usage patterns require different auth models
- Emphasize avoiding bespoke solutions
2. **Quick Reference Table** (from section 2.9)
- Pattern number/name
- Recommended auth models
- Use case
3. **Detailed Pattern Descriptions** (sections 2.1-2.8)
- For each pattern:
- Scenario description
- Diagram (Figures 5-12)
- Recommended authentication model(s)
- Implementation notes
- When to use
- DocRef citations for each
4. **OAuth 2.0 Implementation Details** (section 3.3)
- Basic OAuth 2.0 patterns
- Grant types explained
- Flow diagrams
### Appendix B: API Specification Examples
**Structure:**
1. **Introduction**
- Importance of interface specifications
- Design-driven development
2. **OpenAPI Examples**
- From Part C, section 5
- Complete OpenAPI specifications
- Annotated to explain key elements
3. **AsyncAPI Examples** (if available)
- Event-driven API specifications
4. **Example Code Snippets**
- May need to extract from various sections
- HTTP request/response examples
- Error handling examples
**Note**: The guidelines appear to have limited code examples. May need to create illustrative examples based on the patterns described.
### Appendix E: References and Standards
Should include:
- Table 2 from Part C, section 1.3 (Architectural and deployment patterns)
- External references to:
- MartinFowler.com (Microservices, Observability)
- Nordic APIs (API Management, Multi-cloud, Service Mesh)
- O'Reilly (Observability, Service Mesh)
- API Evangelist (API Discovery)
- NZ Digital Service Design Standard
- Strategy for a Digital Public Service
---
## Key Statistics
- **8 Authentication/Authorization Patterns** identified and documented
- **Part B, section 2**: Primary source for auth patterns (~8 sections, 8 figures)
- **Part C, section 1.3**: Architectural patterns table with 6 pattern types
- **Part C, section 5**: API specification examples (need to read directly)
- **Very limited code samples** in guidelines (conceptual/architectural focus)
---
## Total Results by Part
- **Part B**: ~45 results (majority - authentication patterns, security patterns)
- **Part C**: ~25 results (design patterns, architectural patterns, examples)
- **Part A**: ~12 results (design principles, co-design, dogfooding)
**Note**: Part B dominates pattern-related content, particularly for authentication and authorization.