---
layout: raw-data.njk
---
# Instructions for Creating The New Zealand API Standard

## Objective
Create a comprehensive API Standard document for New Zealand by collating and synthesizing information from the NZ API Guidelines (Parts A, B, and C) using the MCP docref-graphrag server. The Standard must be technically focused, lifecycle-based, and include all DocRef citations for traceability.

## Context
- **Source Material**: NZ API Guidelines database accessible via MCP tools
  - Part A (700 nodes, 12.5%): Foundational concepts, definitions, principles
  - Part B (1,715 nodes, 30.5%): Technical specifications, standards, security requirements
  - Part C (3,197 nodes, 57%): Implementation guidance, procedures, patterns
- **Content Tags**: Use these to filter relevant material
  - `must-or-shall`: Mandatory requirements
  - `should-or-may`: Recommended practices
  - `good-practice`: Best practices and guidance (valuable source material)
  - `definition`: Term definitions
  - `patterns`: Implementation patterns
  - `reference-examples-apis`: Code examples and references
- **User Requirements**:
  - Elevate some 'should-or-may' recommendations to mandatory status
  - Technical focus on Parts B and C (security and development)
  - Include detailed examples and patterns in appendices
  - Lifecycle-based organization (design, develop, deploy, manage)
  - All content must preserve DocRef citations: `([DocRef](url/))`

## Document Structure Requirements

### Formatting Rules
1. **Headings**:
   - Level 1 (`#`): Document title ONLY
   - Level 3 (`###`) or Level 4 (`####`): Main sections (choose based on subdivision depth)
   - Level 1 for appendix titles
   - No in-text numbering (no 1.1, 2.3, etc.)

2. **Lists**:
   - Use ordered lists wherever possible
   - Minimize unordered lists
   - Lists must only follow body paragraphs (never start sections with lists)

3. **Citations**:
   - CRITICAL: Every piece of content must include its DocRef citation
   - Format: `([DocRef](https://docref.digital.govt.nz/nz/dia-apis-part[x]/2022/en/#[id]))`
   - Never omit or paraphrase citations
   - Multiple citations can be combined: `([DocRef](url1/)), ([DocRef](url2/))`

4. **Language**:
   - Use normative language: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY
   - MUST/SHALL = Mandatory requirements
   - SHOULD/MAY = Recommended practices
   - No emojis

## Document Outline

### 1. Title Page
```markdown
# The New Zealand API Standard

**Version**: 1.0
**Status**: Draft
**Date**: [Current Date]
**Authority**: [Issuing Authority]

## About This Standard
[Brief paragraph explaining purpose, relationship to Guidelines]
```

### 2. Introduction Section
Include:
- Purpose and scope of the Standard
- Intended audience (API developers, architects, security teams)
- How to read this document (normative vs. informative)
- Relationship to NZ API Guidelines Parts A, B, C
- Compliance and conformance expectations

### 3. Definitions
Create a definitions section with key terms from the Guidelines:
- API (Application Programming Interface)
- API Developer, API Provider, API Consumer
- API Gateway, API Manager, API Developer Portal, API Catalogue
- REST, OpenAPI, AsyncAPI
- OAuth 2.0, OpenID Connect, JWT
- Authentication, Authorization
- Resource, Endpoint, HTTP verbs (GET, POST, PUT, DELETE)

Each definition MUST include its DocRef citation.

### 4. Main Content Sections (Lifecycle-Based)

#### 4.1 API Design Phase
**Topics to cover** (search using MCP tools):
1. Design principles with DocRef citations
2. API types (REST, async, event-driven) with usage guidance
3. Resource identification and modeling
4. Interface specification requirements (OpenAPI/AsyncAPI)
5. Design-driven development approach
6. API consumer-first design principles

**Key searches** (save all results):
- `semantic_search: "API design principles"` (limit: 30)
- `semantic_search_filtered: tags=["definition"], query="API types REST"` (limit: 40)
- `semantic_search_filtered: tags=["good-practice"], query="API design"` (limit: 30)
- `semantic_search: "design-driven development API specification"` (limit: 30)
- `semantic_search_filtered: tags=["must-or-shall"], part="A", query="design"` (limit: 20)

**Mandatory requirements to include**:
- OpenAPI specification usage (elevate from recommended)
- Design-driven approach
- Consumer consultation requirements

#### 4.2 API Development Phase
**Topics to cover**:
1. REST API implementation standards
   - HTTP methods (GET, POST, PUT, DELETE) - MANDATORY
   - HTTP headers (required headers with Content-Type)
   - Request/response formats (JSON)
   - URI construction standards
2. Error handling and status codes
3. Data validation requirements
4. Testing requirements and approaches

**Key searches** (save all results):
- `semantic_search: "REST API HTTP methods GET POST PUT DELETE"` (limit: 30)
- `semantic_search: "error handling status codes"` (limit: 30)
- `semantic_search: "API testing quality assurance"` (limit: 30)
- `semantic_search: "HTTP headers Content-Type"` (limit: 30)
- `semantic_search_filtered: tags=["must-or-shall"], part="C", query="HTTP"` (limit: 30)
- `semantic_search_filtered: tags=["good-practice"], query="API development testing"` (limit: 30)
- `semantic_search: "data validation JSON schema"` (limit: 20)

**Mandatory requirements to include**:
- Standard HTTP verbs (already mandatory in Guidelines)
- Content-Type headers (already mandatory)
- Error response structure (elevate from recommended)
- Testing in development lifecycle

#### 4.3 API Security Phase
**Topics to cover**:
1. Security design principles
2. Authentication mechanisms
   - OAuth 2.0 (authorisation code, client credentials)
   - API keys
   - OpenID Connect
   - Certificates
3. Authorization patterns
4. Transport security (TLS/HTTPS requirements)
5. Threat protection and validation
6. Confidentiality and integrity

**Key searches** (save all results):
- `semantic_search_filtered: part="B", query="API security authentication authorization OAuth"` (limit: 40)
- `semantic_search: "API security design principles"` (limit: 30)
- `semantic_search: "TLS HTTPS transport security"` (limit: 30)
- `semantic_search: "threat protection validation"` (limit: 30)
- `semantic_search_filtered: tags=["must-or-shall"], part="B"` (limit: 50)
- `semantic_search_filtered: tags=["good-practice"], query="API security"` (limit: 30)
- `semantic_search_filtered: tags=["patterns"], part="B", query="authentication"` (limit: 40)

**Mandatory requirements to include**:
- Authentication for all APIs (elevate from recommended)
- OAuth 2.0 for production APIs (elevate from recommended)
- TLS/HTTPS for all API traffic
- Threat protection mechanisms

#### 4.4 API Deployment Phase
**Topics to cover**:
1. Versioning strategies
   - Header-based versioning (recommended)
   - URL-based versioning (alternative)
2. Backwards compatibility requirements
3. API gateway configuration
4. Release management and deployment processes
5. Environment management (dev, test, production)

**Key searches** (save all results):
- `semantic_search: "API versioning version control backwards compatibility"` (limit: 30)
- `semantic_search: "API gateway deployment"` (limit: 30)
- `semantic_search: "release management lifecycle"` (limit: 30)
- `semantic_search_filtered: tags=["good-practice"], query="versioning deployment"` (limit: 30)
- `semantic_search_filtered: tags=["must-or-shall"], query="backwards compatibility"` (limit: 20)

**Mandatory requirements to include**:
- Backwards compatibility for minor versions (already mandatory)
- Version indication in APIs (elevate from recommended)
- Deprecation notice requirements

#### 4.5 API Management & Operations Phase
**Topics to cover**:
1. API lifecycle management
2. Governance requirements
3. API catalogues and discovery
   - Catalogue requirements
   - API documentation standards
4. Developer portals
5. Monitoring and analytics
6. Rate limiting and throttling
7. Incident and event management
8. Consumer support

**Key searches** (save all results):
- `semantic_search: "API management governance lifecycle"` (limit: 30)
- `semantic_search: "API catalogue discovery documentation"` (limit: 30)
- `semantic_search: "rate limiting throttling performance"` (limit: 30)
- `semantic_search: "monitoring analytics API operations"` (limit: 30)
- `semantic_search_filtered: tags=["good-practice"], query="API management operations"` (limit: 30)
- `semantic_search_filtered: tags=["catalogue"], part="B"` (limit: 30)
- `semantic_search: "developer portal API documentation"` (limit: 30)

**Mandatory requirements to include**:
- API catalogue publication (elevate from recommended)
- Documentation in machine-readable format
- Monitoring and analytics capability
- Rate limiting for production APIs

### 5. Appendices

#### Appendix A: Authentication and Authorization Patterns
Extract detailed patterns from Guidelines Part B:
- Pattern 1: Internal use with customer authorization
- Pattern 2-8: Various authentication scenarios
- OAuth 2.0 flows (authorization code, client credentials, etc.)
- Detailed implementation guidance with examples

**Search strategy**:
- `semantic_search_filtered: part="B", tags=["patterns"], query="authentication authorization"`
- `run_cypher_query: MATCH (n:DocumentNode) WHERE 'patterns' IN n.tags AND n.part = 'B' RETURN n.content, n.url LIMIT 50`

#### Appendix B: API Specification Examples
Include:
1. Complete OpenAPI 3.0 example
2. AsyncAPI example
3. Common API patterns

**Search strategy**:
- `semantic_search: "OpenAPI specification example"`
- Look for content with tags: `["reference-examples-apis"]`

#### Appendix C: Error Handling Reference
Include:
1. Standard error response format
2. HTTP status codes table (organized by GET, POST, PUT, DELETE)
3. Error message guidelines

**Search strategy**:
- `semantic_search: "error handling status codes error messages"`
- Look for tables with status code information

#### Appendix D: Glossary
Comprehensive glossary of all terms with DocRef citations.

**Search strategy**:
- `semantic_search_filtered: tags=["definition", "definitions"], limit=100`

#### Appendix E: References and Standards
1. External standards (W3C, IETF, OWASP)
2. Related NZ Government standards
3. Bibliography with all source DocRefs

## MCP Tool Usage Guide

### Available Tools
1. **mcp__docref-graphrag__get_schema**: Understand database structure
2. **mcp__docref-graphrag__semantic_search**: General topic search
3. **mcp__docref-graphrag__semantic_search_filtered**: Search with tag/part filters
4. **mcp__docref-graphrag__semantic_search_balanced**: Ensure coverage across parts
5. **mcp__docref-graphrag__semantic_search_cross_document**: Find related content across parts
6. **mcp__docref-graphrag__run_cypher_query**: Structural queries (must include LIMIT clause)

### Search Strategy

**IMPORTANT**: The research phase should systematically retrieve and save all search results before beginning content drafting. This creates a traceable, documented foundation of source material that can be referenced throughout the writing process. Additional MCP calls can be made during drafting as needed to clarify specific points or find additional supporting material.

#### Phase 1: Understand Structure
```
mcp__docref-graphrag__get_schema
```

Document the schema structure for reference.

#### Phase 2: Comprehensive Topic Research

**Objective**: Gather and save all relevant content before drafting begins. This ensures:
- Complete coverage of source material
- Traceable provenance for all requirements
- Ability to cross-reference between related topics
- Foundation for elevation decisions

For each major topic area, execute searches and save results:
1. **Broad semantic search** for topic overview
   ```json
   {
     "query": "API design principles and best practices",
     "limit": 30
   }
   ```

2. **Filtered search** for specific content types
   ```json
   {
     "query": "API security authentication",
     "tags": ["must-or-shall"],
     "part": "B",
     "limit": 40
   }
   ```

3. **Balanced search** for comprehensive coverage
   ```json
   {
     "query": "API versioning strategies",
     "total_limit": 30,
     "min_per_part": 10
   }
   ```

#### Phase 3: Extract Definitions

Save comprehensive definitions list:

```json
{
  "query": "API terminology definitions",
  "tags": ["definition"],
  "limit": 100
}
```

Also extract definitions for specific terms:
- API types, components, roles
- Security terms (OAuth, JWT, TLS, etc.)
- Development terms (REST, OpenAPI, AsyncAPI, etc.)
- Management terms (lifecycle, governance, catalogue, etc.)

#### Phase 4: Find Examples and Patterns

Save all pattern and example content:
```json
{
  "query": "authentication patterns OAuth examples",
  "tags": ["patterns", "reference-examples-apis"],
  "limit": 50
}
```

### Important Search Topics

**CRITICAL**: Execute ALL of these searches during the research phase and save the results. Create a structured collection of source material organized by topic area. This research corpus will be the foundation for drafting the Standard.

Execute searches for these key topics and save results:

**Design**:
- "API design principles"
- "resource modeling REST API"
- "OpenAPI AsyncAPI specification"
- "API types REST synchronous asynchronous"

**Development**:
- "HTTP methods GET POST PUT DELETE"
- "HTTP headers Content-Type required"
- "error handling status codes"
- "data validation API"
- "API testing quality"

**Security**:
- "OAuth 2.0 authentication authorization"
- "API keys security"
- "OpenID Connect"
- "TLS HTTPS transport security"
- "threat protection injection"

**Deployment**:
- "API versioning backwards compatibility"
- "API gateway configuration"
- "release management deployment"

**Operations**:
- "API lifecycle management"
- "API catalogue discovery"
- "API governance"
- "rate limiting throttling"
- "monitoring analytics"
- "developer portal"

**Good Practices** (supplement all topic areas):
- Use `tags=["good-practice"]` filter for each major topic
- Good practice content often contains valuable implementation guidance
- Can be elevated to mandatory where appropriate
- Essential for appendices and detailed guidance sections

## Content Synthesis Guidelines

### 1. Elevation of Requirements
Evaluate 'should-or-may' content for elevation to mandatory:

**Criteria for elevation**:
- Essential for security (e.g., OAuth 2.0 for production)
- Critical for interoperability (e.g., OpenAPI specification)
- Foundational best practice (e.g., API testing requirements)
- Already widely adopted as de facto standard

**Examples of elevations**:
- "OpenAPI specification is recommended" → "APIs MUST use OpenAPI specification"
- "OAuth 2.0 should be used for production APIs" → "Production APIs MUST use OAuth 2.0"
- "APIs should be documented in catalogues" → "APIs MUST be published to an API catalogue"
- "Testing should be incorporated" → "APIs MUST include automated testing"

### 2. Content Organization
For each requirement:
1. State the requirement clearly (MUST/SHOULD/MAY)
2. Provide context/rationale (1-2 sentences)
3. Include any specific implementation guidance
4. Add DocRef citation(s)
5. Cross-reference appendices where applicable

Example structure:
```markdown
#### HTTP Methods

APIs MUST use standard HTTP methods for REST operations ([DocRef](url1/)).

Access to REST APIs must be via the standard HTTP verbs: GET, PUT, POST, DELETE in line with the W3C Standard ([DocRef](url2/)).

The following methods are defined:

1. **GET**: For retrieval of information. GET operations are safe and idempotent ([DocRef](url3/))
2. **POST**: To create a resource or spawn an action ([DocRef](url4/))
3. **PUT**: To update an existing resource item ([DocRef](url5/))
4. **DELETE**: To delete an existing resource item ([DocRef](url6/))

See Appendix C for detailed usage patterns and examples.
```

### 3. Citation Management
- Every substantive statement needs a DocRef
- When combining multiple sources, use multiple citations
- Preserve the exact URL from the MCP results
- If paraphrasing, still include the source citation
- For tables/lists, cite each row/item if from different sources

### 4. Appendix Content
Appendices should be detailed and practical:
- Include code examples where provided in Guidelines
- Preserve example structure and formatting
- Add explanatory text for context
- Cross-reference to main body requirements

## Quality Checklist

Before considering the Standard complete, verify:

- [ ] Every section has content from the Guidelines with DocRef citations
- [ ] All mandatory requirements clearly use MUST/MUST NOT
- [ ] All recommendations clearly use SHOULD/SHOULD NOT/MAY
- [ ] No in-text numbering (1.1, 2.3 format)
- [ ] Lists only follow body paragraphs
- [ ] Ordered lists used throughout (except where unordered is more appropriate)
- [ ] Main headings at level 3 or 4 (consistent choice throughout)
- [ ] Document title at level 1 only
- [ ] All definitions included in Definitions section or Appendix D
- [ ] All authentication patterns included in Appendix A
- [ ] Complete examples in Appendix B
- [ ] Error handling reference in Appendix C
- [ ] Comprehensive glossary in Appendix D
- [ ] All external references in Appendix E
- [ ] Cross-references work correctly
- [ ] Document flows logically through lifecycle phases
- [ ] Technical accuracy maintained from source material
- [ ] Consistent terminology throughout

## Estimated Output

**File**: `nz-api-standard.md`

**Length**: Approximately 10,000-15,000 words

**Structure**:
- Title and Introduction: ~500 words
- Definitions: ~800 words
- Design Phase: ~1,500 words
- Development Phase: ~2,000 words
- Security Phase: ~2,500 words
- Deployment Phase: ~1,200 words
- Operations Phase: ~1,800 words
- Appendix A (Auth Patterns): ~2,000 words
- Appendix B (Examples): ~1,500 words
- Appendix C (Error Reference): ~800 words
- Appendix D (Glossary): ~1,000 words
- Appendix E (References): ~400 words

**Citations**: 250-400+ DocRef citations throughout

## Implementation Steps

1. **Setup**: Verify MCP server connection to docref-graphrag
2. **Schema Review**: Run get_schema to understand database structure

3. **Research Phase** (CRITICAL - DO THIS FIRST):
   - Execute ALL searches listed in "Important Search Topics" section
   - Save all results in an organized structure (by topic/section)
   - Document the search queries used for traceability
   - Create a research corpus with:
     - All mandatory requirements (must-or-shall tags)
     - All recommendations (should-or-may tags)
     - All good practices (good-practice tags)
     - All definitions (definition tags)
     - All patterns and examples (patterns, reference-examples-apis tags)
   - This corpus serves as the traceable foundation for all drafting
   - Note: Additional targeted searches can be performed during drafting as needed

4. **Definitions Extraction**: From saved research, compile all definitions with citations

5. **Content Drafting**:
   - Write each section following lifecycle structure
   - Reference saved research corpus for all content
   - Perform additional MCP searches as needed for clarification
   - Maintain clear traceability to source material

6. **Requirements Elevation**: Review saved research to identify recommendations for elevation to mandatory

7. **Appendices Creation**: Compile detailed appendices from patterns and examples in saved research

8. **Citation Verification**: Ensure all content has DocRef citations from research corpus

9. **Cross-Reference**: Add internal document cross-references

10. **Quality Review**: Run through checklist

11. **Final Format**: Ensure markdown formatting compliance

## Notes for LLM Execution

- **Research First**: Complete comprehensive research phase before drafting any content
- **Save Everything**: Document all search results in an organized structure for reference
- **Traceability**: Every requirement must trace back to saved research with DocRef citations
- **Good Practice Tags**: Don't overlook content tagged as "good-practice" - it often contains essential guidance
- **Supplemental Searches**: While the saved research corpus is the foundation, perform additional MCP calls during drafting as needed for:
  - Clarifying specific points
  - Finding additional supporting material
  - Verifying cross-references
  - Expanding on examples
- Work systematically through each section
- Preserve the exact wording from Guidelines where it's already clear and normative
- Synthesize when combining multiple sources
- Be explicit about elevation decisions (document why something is elevated)
- Maintain traceability through citations
- Ask clarifying questions if user requirements are ambiguous
- The goal is a usable, authoritative Standard document, not a copy of the Guidelines