Development 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: Development Phase Research
---

# Development Phase Research Results

**Purpose**: This file contains all research results for the API Development Phase section of the NZ API Standard.

**Total Searches**: 7
**Total Results**: 153 results
**Date Generated**: 2025-11-03

---

## Search 1: REST API HTTP Methods (GET, POST, PUT, DELETE)

**Query Type**: semantic_search
**Query**: "REST API HTTP methods GET POST PUT DELETE"
**Limit**: 30
**Purpose**: Capture mandatory requirements and definitions for HTTP verbs

### Key Findings

**MANDATORY REQUIREMENT FOUND**:
- "Access to REST APIs must be via the standard HTTP verbs: GET, PUT, POST, DELETE in line with the W3C Standard." ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section4-para1))
- Tags: [must-or-shall, standards_review]
- Score: 0.9097

### Results (30 items)

1. **HTTP verbs mandatory** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section4-para1))
   - Part: C | Type: para | Level: 2
   - Content: "Access to REST APIs must be via the standard HTTP verbs: GET, PUT, POST, DELETE in line with the W3C Standard."
   - Tags: [must-or-shall, standards_review]
   - Score: 0.9097
   - **MANDATORY**

2. **Response Header Usage GET POST PUT DELETE** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb2-thr1))
   - Part: C | Type: table | Level: 3
   - Score: 0.8793

3. **Header Usage GET POST PUT DELETE** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb1-thr1))
   - Part: C | Type: table | Level: 3
   - Score: 0.8776

4. **1.4. HTTP verbs (Full Section)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section4))
   - Part: C | Type: section | Level: 1
   - Content: Full table with verb definitions and common usage
   - Tags: [must-or-shall, standards_review]
   - Score: 0.8757

5. **POST definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part8-para1-l23))
   - Part: C | Type: list | Level: 2
   - Content: "One of the most common HTTP methods for retrieving from and sending data to a server, the POST method sends data to the server and creates a new resource. The resource it creates is subordinate to some other parent resource. When a new resource is POSTed to the parent, the API service will automatically associate the new resource by assigning it a new resource URI. In short, this method is used to create a new data entry."
   - Tags: [definition, definitions]
   - Score: 0.8660

6. **POST definition (Part B)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part14-para1-l18))
   - Part: B | Type: list | Level: 2
   - Same content as above
   - Tags: [definition, definitions]
   - Score: 0.8660

7. **DELETE definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part8-para1-l16))
   - Part: C | Type: list | Level: 2
   - Content: "One of the most common HTTP methods, DELETE is used to delete a resource specified by its URI."
   - Tags: [definition, definitions]
   - Score: 0.8617

8. **DELETE definition (Part B)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part14-para1-l15))
   - Part: B | Type: list | Level: 2
   - Same content as above
   - Tags: [definition, definitions]
   - Score: 0.8617

9. **HTTP as transport layer** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part7-para3-tb1-tr3-td2))
   - Part: C | Type: table | Level: 4
   - Content: "Communication between client computers and web servers is done by sending HTTP requests and receiving HTTP responses. In practice, most RESTful APIs use HTTP as a transport layer and rely on the use of HTTP verbs, like POST, GET, PUT and DELETE."
   - Tags: [definition, definitions]
   - Score: 0.8595

10. **PUT definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part8-para1-l25))
    - Part: C | Type: list | Level: 2
    - Content: "One of the most common HTTP methods for retrieving from and sending data to a server, the PUT method is most often used to update an existing resource. If you want to update a specific resource (which comes with a specific URI), you can call the PUT method to that resource URI with the request body containing the complete new version of the resource you are trying to update."
    - Tags: [definition, definitions]
    - Score: 0.8581

11-30. [Additional results on PUT usage, idempotency, status codes, REST API tutorials, and HTTP verb tables]

---

## Search 2: Error Handling Status Codes

**Query Type**: semantic_search
**Query**: "error handling status codes"
**Limit**: 30
**Purpose**: Capture error handling requirements and HTTP status code usage

### Key Findings

**Important Content**:
- Error handling section: 1.13 ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section13-title))
- Error responses must be both human- and machine-consumable
- Should contain: HTTP status code, API-specific error code, human-readable message

### Results (30 items)

1. **1.13. Error handling** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section13-title))
   - Part: C | Type: section | Level: 2
   - Score: 0.8991

2. **POST or PUT response status codes** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section13-para5-tb1-tr10))
   - Part: C | Type: table | Level: 4
   - Tags: [definition, definitions]
   - Score: 0.8675

3. **GET response status codes** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section13-para5-tb1-tr1-td1))
   - Part: C | Type: table | Level: 5
   - Tags: [definition, definitions]
   - Score: 0.8649

4. **Error code in response** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part5-para3-ex3-pf1-pfl247))
   - Part: C | Type: example | Level: 4
   - Content: "description: An error code — should be used in conjunction with the HTPP response code."
   - Score: 0.8602

5. **1.13.1. HTTP status codes** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section13-h1))
   - Part: C | Type: heading | Level: 2
   - Score: 0.8568

6. **Error items array** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part5-para3-ex3-pf1-pfl242))
   - Part: C | Type: example | Level: 4
   - Content: "description: An array of error items containing error codes and descriptions. Note that the error descriptions will be normalised."
   - Tags: [definition, definitions]
   - Score: 0.8552

7. **DELETE response status codes** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section13-para5-tb1-tr19-td1))
   - Part: C | Type: table | Level: 5
   - Tags: [definition, definitions]
   - Score: 0.8546

8-30. [Additional results on error response formats, status codes by method, error messages, and API-specific error codes]

**Key Error Handling Requirements**:
- Error responses must contain:
  1. HTTP status code ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section13-para2-1))
  2. API-specific error code ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section13-para2-2))
  3. Human-readable message ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section13-h3))
- Error handling importance ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section13-para2))
  - Tags: [good-practice, must-or-shall, should-or-may, standards_review]
  - "Error handling is important because API consumers see the API as a black box, and when an error occurs they need to know how to handle it."

---

## Search 3: API Testing Quality Assurance

**Query Type**: semantic_search
**Query**: "API testing quality assurance"
**Limit**: 30
**Purpose**: Capture testing requirements and QA practices

### Key Findings

**Testing Requirements**:
- Tests can be written against interface specification early
- Tests should be incorporated into automated build process
- API code should not progress through SDLC environments until successful test execution

### Results (30 items)

1. **Support for testing** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section3-para8-3))
   - Part: A | Type: para | Level: 3
   - Content: "support for testing of their application in use of the API"
   - Score: 0.8846

2. **Internal development and testing** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-para3-1))
   - Part: A | Type: para | Level: 2
   - Content: "support the internal development and testing of APIs"
   - Score: 0.8697

3. **1. API security** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-title))
   - Part: B | Type: part | Level: 1
   - Score: 0.8615

4. **Penetration test** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part4-section2-para7-2))
   - Part: B | Type: para | Level: 3
   - Content: "penetration test — once an API is developed and published (testable)."
   - Score: 0.8564

5. **Reporting issues with API** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section3-para8-4))
   - Part: A | Type: para | Level: 3
   - Content: "reporting issues with the API."
   - Tags: [good-practice, standards_review]
   - Score: 0.8509

6-9. [Security validation, threat protection, QoS functions]

10. **Test-driven development** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para42))
    - Part: C | Type: para | Level: 2
    - 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."
    - Tags: [must-or-shall, should-or-may, good-practice, standards_review]
    - Score: 0.8470
    - **Elevation Candidate**: Testing as part of SDLC

11-30. [Additional results on API keys for monitoring, integrity/confidentiality, sandbox environments, API evaluation]

---

## Search 4: HTTP Headers Content-Type

**Query Type**: semantic_search
**Query**: "HTTP headers Content-Type"
**Limit**: 30
**Purpose**: Capture header requirements, particularly Content-Type

### Key Findings

**MANDATORY REQUIREMENTS**:
1. Response headers must contain Content-Type ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part4-section2-para1))
2. Content-Type header required for POST, PUT, DELETE requests ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part4-section1-para6))
3. Content-Type must be returned in response ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part4-section2-para2))

### Results (30 items)

1. **1.6. HTTP headers** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-title))
   - Part: C | Type: section | Level: 2
   - Score: 0.9120

2. **Response headers must contain Content-Type** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part4-section2-para1))
   - Part: C | Type: para | Level: 2
   - Content: "Response headers are supplied by the provider and must contain Content-Type."
   - Tags: [must-or-shall, standards_review]
   - Score: 0.9077
   - **MANDATORY**

3. **Content-Type (table header)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb2-tr1-td1))
   - Part: C | Type: table | Level: 4
   - Score: 0.9004

4. **Content-Type (request)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part4-section1-para1-2))
   - Part: C | Type: para | Level: 3
   - Score: 0.9004

5. **Content-Type (request table)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb1-tr2-td1))
   - Part: C | Type: table | Level: 4
   - Score: 0.9004

6. **Content-Type required for POST, PUT, DELETE** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part4-section1-para6))
   - Part: C | Type: para | Level: 2
   - Content: "The Content-type header is required for all requests that include a request body like POST, PUT, DELETE."
   - Tags: [must-or-shall, standards_review]
   - Score: 0.8919
   - **MANDATORY**

7. **Content-Type must indicate format and version** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part4-section2-para2))
   - Part: C | Type: para | Level: 2
   - Content: "The Content-Type must be returned in the response, and indicate the format type the response content is in, for example, 'Content-Type: application/json'. The Content-Type header should also include the version of the API that processed the request, for example, 'Content-Type: application/json,version=1.1'."
   - Tags: [must-or-shall, should-or-may, standards_review]
   - Score: 0.8876
   - **MANDATORY** (format), **RECOMMENDED** (version)

8. **Content-Type table row** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb1-tr2))
   - Part: C | Type: table | Level: 3
   - Content: "Content-Type Indicates the format of the payload provided on the request. If not supported by the server, API responds with 415 (Unsupported Media Type) N/A Required Required N/A"
   - Score: 0.8815

9-30. [Additional results on Accept headers, content negotiation, version indication, custom X-HTTP headers, and Content-Type examples]

**Summary of Content-Type Requirements**:
- **Request**: Required for POST, PUT, DELETE (with body)
- **Response**: Always required, must indicate format type
- **Should include**: API version (recommended)
- **Error handling**: 415 Unsupported Media Type if format not supported
- **Error handling**: 406 Not Acceptable if client can't handle response format

---

## Search 5: HTTP (Mandatory Requirements in Part C)

**Query Type**: semantic_search_filtered
**Query**: "HTTP"
**Tags Filter**: ["must-or-shall"]
**Part Filter**: C
**Limit**: 30
**Purpose**: Find all mandatory HTTP-related requirements

### Results (3 items only)

1. **Table 3: HTTP verbs** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section4-para1-tb1))
   - Part: C | Type: table
   - Content: Full table defining GET, POST, PUT, DELETE, OPTIONS, PATCH, HEAD
   - Tags: [definition, definitions, should-or-may, good-practice, must-or-shall, standards_review]
   - Score: 0.8474

2. **1.4. HTTP verbs (section)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section4))
   - Part: C | Type: section
   - Full section with table
   - Tags: [must-or-shall, standards_review]
   - Score: 0.8473

3. **Standard HTTP verbs mandatory** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section4-para1))
   - Part: C | Type: para
   - Content: "Access to REST APIs must be via the standard HTTP verbs: GET, PUT, POST, DELETE in line with the W3C Standard."
   - Tags: [must-or-shall, standards_review]
   - Score: 0.8372

**Note**: Only 3 results indicates HTTP-related mandatory requirements are well-defined but limited in scope.

---

## Search 6: API Development Testing (Good Practice)

**Query Type**: semantic_search_filtered
**Query**: "API development testing"
**Tags Filter**: ["good-practice"]
**Limit**: 30
**Purpose**: Capture testing best practices

### Results (15 items)

1. **Test-driven development with SDLC gates** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para42))
   - Part: C | Type: para
   - 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."
   - Tags: [must-or-shall, should-or-may, good-practice, standards_review]
   - Score: 0.9026
   - **Elevation Candidate**: SDLC testing requirements

2. **Sandbox for development/testing** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section4-para4-3))
   - Part: A | Type: para
   - Content: "Where the API is for development / testing purposes only, registration should be self-service and the ability for an application developer to 'try out' the API should be provided. This is commonly known as 'providing a sandbox'."
   - Tags: [definition, definitions, should-or-may, good-practice, standards_review]
   - Score: 0.8727

3. **Design for the consumer** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section1))
   - Part: A | Type: section
   - Content includes: "providing sandbox APIs so application developers can try out APIs and develop in parallel"
   - Tags: [to-review, good-practice, should-or-may, standards_review]
   - Score: 0.8697

4. **Collaborative, flexible development** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section2-para2))
   - Part: A | Type: para
   - 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."
   - Tags: [good-practice, should-or-may, standards_review]
   - Score: 0.8678

5. **Developer investment in API** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para2))
   - Part: C | Type: para
   - 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."
   - Tags: [good-practice, standards_review]
   - Score: 0.8636

6. **Dogfooding** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section5))
   - Part: A | Type: section
   - Content: Internal use validates design - "build for inside use, then expose"
   - Tags: [good-practice, standards_review]
   - Score: 0.8616

7-15. [Additional results on error handling, developer portals, stability/velocity, test platform importance, API publication]

---

## Search 7: Data Validation JSON Schema

**Query Type**: semantic_search
**Query**: "data validation JSON schema"
**Limit**: 20
**Purpose**: Capture validation requirements and JSON usage

### Results (20 items)

1. **JSON / JSON Schema** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part7-para3-tb1-tr5-td1))
   - Part: C | Type: table | Level: 4
   - Tags: [definition, definitions]
   - Score: 0.8897

2. **Validate JSON content** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6-para1-tb1-tr3-td2-l3))
   - Part: B | Type: list | Level: 6
   - Content: "* Validate JSON content."
   - Score: 0.8870

3. **Input validation requirements** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part11-section6-para1-tb1-tr3-td2))
   - Part: B | Type: table | Level: 5
   - Content: "* Validate input secure parsing and strong typing. * Validate incoming content-type application / JSON. * Validate JSON content. * Validate XML (schema and format). * Scan attachments. * Produce valid HTTP return code. * Validate response type."
   - Score: 0.8590

4-20. [Schema references in OpenAPI examples, JSON definitions, content-type validation, XML schema validation]

**Key Validation Concepts**:
- JSON is the standard format for REST APIs
- Schema validation ensures data integrity
- Validation includes: secure parsing, strong typing, content-type checking, format validation
- JSON Schema used in OpenAPI specifications

---

## Summary of Development Phase Findings

### Mandatory Requirements Identified

1. **HTTP Verbs**: MUST use standard HTTP verbs (GET, POST, PUT, DELETE) per W3C Standard
2. **Content-Type Header**:
   - MUST be included in responses
   - MUST be included in requests with body (POST, PUT, DELETE)
   - MUST indicate format type
3. **Error Handling**: Responses should contain HTTP status code, API error code, human-readable message

### Strong Elevation Candidates

1. **Testing in SDLC**: "API code should not be able to progress through SDLC environments until successful test execution"
2. **Sandbox Environment**: Providing sandbox for developers to try APIs
3. **Automated Testing**: Incorporating tests into automated build process
4. **Error Response Structure**: Standardized error format for machine and human consumption

### Key Development Topics to Include

1. **REST API Implementation**:
   - HTTP verbs (GET for retrieval, POST for creation, PUT for update, DELETE for deletion)
   - Idempotency (GET and PUT are idempotent, POST is not)
   - Safe operations (GET is safe, others modify state)

2. **HTTP Headers**:
   - Content-Type (mandatory for requests and responses)
   - Accept (content negotiation)
   - Custom X-HTTP headers
   - Request tracking headers

3. **Error Handling**:
   - HTTP status codes by method (GET, POST, PUT, DELETE)
   - Error response format (status code + error code + message)
   - Avoiding information leakage
   - Machine and human readability

4. **Data Validation**:
   - JSON as standard format
   - Schema validation
   - Input validation (secure parsing, strong typing)
   - Content-type validation

5. **Testing Requirements**:
   - Test-driven development
   - Automated testing in build process
   - SDLC gates based on test success
   - Sandbox environments
   - Penetration testing

6. **Quality Practices**:
   - Specification-first development (enables early testing)
   - Stubs for early test execution
   - Regression test automation
   - Developer feedback loops

### HTTP Status Codes by Method

**GET**:
- 200 OK (successful)
- 404 NOT FOUND
- 401 UNAUTHORISED
- 429 TOO MANY REQUESTS
- 500 SERVER ERROR

**POST/PUT**:
- 200 OK (updated)
- 201 CREATED (new resource)
- 400 BAD REQUEST (validation failed)
- 401 UNAUTHORISED
- 404 NOT FOUND
- 405 METHOD NOT ALLOWED
- 429 TOO MANY REQUESTS
- 500 SERVER ERROR

**DELETE**:
- 200 OK (with body)
- 204 NO CONTENT (without body)
- 404 NOT FOUND
- 401 UNAUTHORISED
- 500 SERVER ERROR

### External References

- W3C Standard for HTTP methods
- REST API Tutorial (HTTP Methods, Status Codes)
- OWASP (input validation, security practices)

---

## Notes for Drafting

1. **Structure**: Development section should cover:
   - HTTP verbs and their proper usage
   - HTTP headers (request and response)
   - Data formats (JSON primary)
   - Error handling and status codes
   - Testing and quality assurance
   - Validation requirements

2. **Elevation Decisions**: Testing requirements appear multiple times with mixed tags (must-or-shall + should-or-may + good-practice), suggesting strong candidate for elevation

3. **Cross-references**:
   - Links to Security (Part B) for threat protection
   - Links to Design for specification-driven development
   - Links to Operations for monitoring and analytics

4. **Practical Guidance**: Extensive status code tables and examples available for Appendix C