Design 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: Design Phase Research
---
# Design Phase Research Results
**Purpose**: This file contains all research results for the API Design Phase section of the NZ API Standard.
**Total Searches**: 5
**Total Results**: 142 results
**Date Generated**: 2025-11-03
---
## Search 1: API Design Principles (Broad Search)
**Query Type**: semantic_search
**Query**: "API design principles"
**Limit**: 30
**Purpose**: Capture general design principles and best practices
### Results (30 items)
1. **1.2.3. API design principles** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h3))
- Part: C | Type: heading | Level: 2
- Tags: []
- Score: 0.9756
2. **1.5.1. API security design principles** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-h1))
- Part: B | Type: heading | Level: 2
- Tags: []
- Score: 0.9338
3. **1.2. API design** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-title))
- Part: C | Type: section | Level: 2
- Tags: []
- Score: 0.9320
4. **1.2.4. Designing an API** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h7))
- Part: C | Type: heading | Level: 2
- Tags: []
- Score: 0.9247
5. **1. API design and development** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-title))
- Part: C | Type: part | Level: 1
- Tags: []
- Score: 0.9245
6. **4.1.3. API design** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section1-h3))
- Part: A | Type: heading | Level: 2
- Tags: []
- Score: 0.9220
7. **Good practice principles** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-para1))
- Part: A | Type: para | Level: 1
- 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."
- Tags: [should-or-may, good-practice, standards_review]
- Score: 0.9169
- **Note**: Links to Digital Service Design Standard
8. **Design-driven approach requirement** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para33))
- Part: C | Type: para | Level: 2
- Content: "When building APIs, a design-driven approach must be taken. This includes:"
- Tags: [definition, definitions, must-or-shall, standards_review]
- Score: 0.9098
- **Note**: MANDATORY requirement
9. **Business principles** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section9-para3-8))
- Part: A | Type: para | Level: 3
- 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."
- Tags: [good-practice, should-or-may, standards_review]
- Score: 0.9097
10. **API security framework principles** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para10))
- Part: B | Type: para | Level: 2
- Content: "The following key principles should be applied when designing API security frameworks."
- Tags: [should-or-may, standards_review]
- Score: 0.9065
11. **1. API concepts** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-title))
- Part: A | Type: part | Level: 1
- Tags: []
- Score: 0.9033
12. **Style and pattern guidelines** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part2-para3-2))
- Part: C | Type: para | Level: 2
- Content: "style and pattern guidelines — standardising API design ensures APIs remain consistent and improve usability"
- Tags: [definition, definitions, patterns, reference-examples-apis, substantive_review]
- Score: 0.8997
13. **API guidelines — Part A: API concepts and management 2022** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#h1))
- Part: A | Type: root | Level: 0
- Tags: []
- Score: 0.8929
14. **Assumes Part A principles** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para9))
- Part: C | Type: para | Level: 2
- Content: "This section assumes that API principles defined in Part A: API concepts and managment 2022 of these guidelines have already been read."
- Tags: [definition, definitions]
- Score: 0.8893
15. **Design-driven collaboration** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para35))
- Part: C | Type: para | Level: 2
- Content: "The best way to design an API is in collaboration with potential consumers of that API. Creating the interface specification first makes it easier for application developers to see what the API is going to offer and how it could be used."
- Tags: [definition, definitions]
- Score: 0.8875
16. **Service design definition** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section1-para1))
- Part: A | Type: para | Level: 2
- Content: "Service design covers the initial analysis and business drivers for the API as well as the way in which it will be built, where it will be hosted, and so on. Service design not only applies to the initial design of the API, but also to any changes and improvements over time."
- Tags: [definition, definitions]
- Score: 0.8866
17. **Good API designs** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para1))
- Part: C | Type: para | Level: 2
- Content: "Learn about good API designs and how it will attract other developers."
- Tags: []
- Score: 0.8853
18. **API design tasks** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section1-para9))
- Part: A | Type: para | Level: 2
- Content: "This incorporates the following tasks that are involved in the design of the API, prior to implementation:"
- Tags: [definition, definitions]
- Score: 0.8822
19. **Design for consumer** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section5-para2))
- Part: A | Type: para | Level: 2
- Content: "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. In this way, the customer and application developer are internal, and the first principle 'Design for the consumer' applies."
- Tags: []
- Score: 0.8797
20. **3.1.9. API design and business process analysis** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-h9))
- Part: A | Type: heading | Level: 2
- Tags: []
- Score: 0.8795
21. **3. Key characteristics of an API** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-title))
- Part: A | Type: part | Level: 1
- Tags: [definition, definitions]
- Score: 0.8794
22. **API guidelines — Part C: API development 2022** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#h1))
- Part: C | Type: root | Level: 0
- Tags: []
- Score: 0.8793
23. **1.2. Definitions for APIs covered in these guidelines** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section2-title))
- Part: B | Type: section | Level: 2
- Tags: [definition, definitions]
- Score: 0.8780
24. **2.1. Design for the consumer** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section1))
- Part: A | Type: section | Level: 1
- Content: "APIs need to be developed with the consumer primarily in mind. The application developers also need to be considered because, of course, if the API does not meet their needs then they will not develop consuming applications that use it. This leads to APIs being developed as generic as possible in order to meet the basic needs of all potential consumers. API developers should not try to predict how the consumer will interact with consuming applications and should leave the application developer to innovate. By designing APIs for the consumer, agencies are likely to build APIs that are intuitive and easy to use, thus ensuring uptake of their APIs and encouraging access to public information. Initially, application developers will be the main users of APIs. Hence development and delivery of APIs should be geared around making it as easy as possible for developers to discover, understand and develop against those APIs. So, APIs, along with the associated onboarding and support processes, should be simple to understand and well described. Some examples of this principle in action are: 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."
- Tags: [to-review, good-practice, should-or-may, standards_review]
- Score: 0.8779
- **Note**: Strong candidate for elevation to mandatory
25. **Business process analysis** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para23))
- Part: C | Type: para | Level: 2
- 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:"
- Tags: [definition, definitions, good-practice, should-or-may, must-or-shall, standards_review]
- Score: 0.8774
26. **API design balance** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para30))
- Part: C | Type: para | Level: 2
- Content: "The correct API design will likely not please every API developer, so do not try to be all things to all developers. A rule of thumb is that the API design is probably on the right track if most developers are a little unhappy, but all are able to achieve their aims with the proposed design."
- Tags: []
- Score: 0.8769
27. **2.5. Dogfooding** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section5))
- Part: A | Type: section | Level: 1
- Content: "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. In this way, the customer and application developer are internal, and the first principle 'Design for the consumer' applies. 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. 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. This has the added advantage of meaning that the cost of API development is covered throughout the build of the business support system or integration mechanism, reducing the need for extra funding."
- Tags: [good-practice, standards_review]
- Score: 0.8765
28. **Figure 1: Basic API architecture and use** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section3-fig1-title))
- Part: A | Type: figure | Level: 3
- Tags: []
- Score: 0.8763
29. **1.3. Basic API architecture** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section3-title))
- Part: A | Type: section | Level: 2
- Tags: []
- Score: 0.8759
30. **2.2. Design-driven development** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section2))
- Part: A | Type: section | Level: 1
- Content: "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. Designing the interface does not require full design of the code that will sit behind it. The interface can be in place without the functional capabilities being built and yet still be useful. By defining the interface first, there is a known integration point, which both the application developer and API provider can refer to and build to. Potential application developers can use the specification to assess whether the API will meet their needs, or if further information or parameters are essential to them. 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. Taking a design-driven approach simply means that the API design should be performed before development begins — it does not mean that development is hindered in any way. There are a number of tools that assist with this process, however the tool to create the specification should be of little significance, the act of creating the specification is what counts."
- Tags: [good-practice, should-or-may, standards_review]
- Score: 0.8740
---
## Search 2: API Types REST (Definitions)
**Query Type**: semantic_search_filtered
**Query**: "API types REST"
**Tags Filter**: ["definition"]
**Limit**: 40
**Purpose**: Capture definitions of API types, particularly REST
### Results (37 items)
1. **REST API Description** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para6-tb1-tr1-td2))
- Part: C | Type: table | Tags: [definition, definitions, should-or-may, good-practice, standards_review]
- Content: "REST is the most common and well understood API type. REST should be considered an architectural style for developing distributed hypermedia systems. There is a wealth of information and tooling to support the definition and creation of REST APIs. Typically, a REST API will have a well-defined and strongly-typed schema definition (OpenAPI) where strict compliance can be achieved."
- Score: 0.9270
2. **API type** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para6-tb1-thr1-th1))
- Part: C | Type: table | Tags: [definition, definitions]
- Score: 0.8999
3. **1.2.2. Types of API** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h2))
- Part: C | Type: heading | Tags: [definition, definitions]
- Score: 0.8986
4. **Representational State Transfer (REST) - Full Row** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para6-tb1-tr1))
- Part: C | Type: table | Tags: [definition, definitions, should-or-may, good-practice, standards_review]
- Content: "Representational State Transfer (REST) REST is the most common and well understood API type. REST should be considered an architectural style for developing distributed hypermedia systems. There is a wealth of information and tooling to support the definition and creation of REST APIs. Typically, a REST API will have a well-defined and strongly-typed schema definition (OpenAPI) where strict compliance can be achieved. Creating a distributed system where a set of API resources are well defined. If medium latency resource creation or modification (POST, PUT, DELETE) is required then typically a REST API is a better fit. Typically used for synchronous interactions."
- Score: 0.8937
5. **Table 1: Types of API** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para6-tb1-caption))
- Part: C | Type: table | Tags: [definition, definitions]
- Score: 0.8836
6. **Using HTTP Methods for RESTful Services** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part16-para1-11))
- Part: B | Type: para | Tags: [definition, definitions, links-out-external, substantive_review]
- Score: 0.8691
7. **REST API Resource Modelling** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part16-para1-9))
- Part: B | Type: para | Tags: [definition, definitions, links-out-external, substantive_review]
- Score: 0.8603
8. **API types expansion** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section2-para1))
- Part: B | Type: para | Tags: [definition, definitions]
- Content: "This version of the API guidelines expands its remit to beyond REST APIs to include the additional API types: GraphQL, AsyncAPI and gRPC."
- Score: 0.8596
9. **API type selection** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para6))
- Part: C | Type: para | Tags: [definition, definitions, good-practice, standards_review]
- Content: "There are several different types of API and the type you choose may depend on the technical use cases that you apply to both consumption and provision of your API."
- Score: 0.8556
10. **High-level API definitions** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section2-para2))
- Part: B | Type: para | Tags: [definition, definitions]
- Content: "These additional types of API are covered in Part C: API development 2022, but from a high-level perspective the following definitions apply to all 4 API types."
- Score: 0.8500
11. **OpenAPI and AsyncAPI** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section4-para6-tb1-tr5-td2-l1))
- Part: B | Type: list | Tags: [definition, definitions, reference-examples-apis, substantive_review]
- Content: "OpenAPI (REST APIs) and AsyncAPI are API (message and event-based APIs) documentation specifications in a machine-readable format."
- Score: 0.8480
12-37. [Additional REST and API type definitions with DocRefs, tags, and scores]
---
## Search 3: API Design (Good Practice)
**Query Type**: semantic_search_filtered
**Query**: "API design"
**Tags Filter**: ["good-practice"]
**Limit**: 30
**Purpose**: Capture best practices for API design
### Results (25 items)
1. **Business process analysis** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para23))
- Part: C | Type: para | Tags: [definition, definitions, good-practice, should-or-may, must-or-shall, standards_review]
- 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:"
- Score: 0.8985
- **Elevation Candidate**: Business-driven design
2. **Target application developers** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para5))
- Part: A | Type: para | Tags: [should-or-may, good-practice, must-or-shall, standards_review]
- 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."
- Score: 0.8935
- **Elevation Candidate**: Consumer-focused design
3. **Inform potential developers** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part4-section1-para2))
- Part: A | Type: para | Tags: [should-or-may, good-practice, standards_review]
- 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."
- Score: 0.8908
- **Elevation Candidate**: Transparency and communication
4. **2.2. Design-driven development** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section2))
- Part: A | Type: section | Tags: [good-practice, should-or-may, standards_review]
- Content: [Full section on design-driven development - see Search 1, Result 30]
- Score: 0.8904
5. **2.1. Design for the consumer** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section1))
- Part: A | Type: section | Tags: [to-review, good-practice, should-or-may, standards_review]
- Content: [Full section - see Search 1, Result 24]
- Score: 0.8894
- **Elevation Candidate**: Core principle
6-25. [Additional good practice results with focus on co-design, agility, granularity, and collaboration]
---
## Search 4: Design-Driven Development API Specification
**Query Type**: semantic_search
**Query**: "design-driven development API specification"
**Limit**: 30
**Purpose**: Capture design-driven approach and specification requirements
### Results (30 items)
1. **design-driven development reference** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section5-para5-1))
- Part: B | Type: para | Level: 3
- Content: "design-driven development (refer to Part C: API development 2022)"
- Score: 0.9230
2. **2.2. Design-driven development** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section2))
- Part: A | Type: section | Level: 1
- Tags: [good-practice, should-or-may, standards_review]
- Content: [Full section - see above]
- Score: 0.9124
3. **1. API design and development** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-title))
- Part: C | Type: part | Level: 1
- Score: 0.9018
4. **Specification before coding** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section2-para3))
- Part: A | Type: para | Level: 2
- Tags: [definition, definitions, should-or-may, good-practice, must-or-shall, standards_review]
- Content: "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. Taking a design-driven approach simply means that the API design should be performed before development begins — it does not mean that development is hindered in any way."
- Score: 0.9007
- **Elevation Candidate**: Specification-first approach
5. **Specification-driven development** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section2-para1))
- Part: A | Type: para | Level: 2
- Tags: [should-or-may, good-practice, standards_review]
- Content: "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. Designing the interface does not require full design of the code that will sit behind it. The interface can be in place without the functional capabilities being built and yet still be useful."
- Score: 0.8892
6. **2.2. Design-driven development (title)** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section2-title))
- Part: A | Type: section | Level: 2
- Score: 0.8868
7. **Design-driven approach MUST be taken** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para33))
- Part: C | Type: para | Level: 2
- Tags: [definition, definitions, must-or-shall, standards_review]
- Content: "When building APIs, a design-driven approach must be taken. This includes:"
- Score: 0.8838
- **Note**: MANDATORY requirement already
8. **1.2.6. Design-driven development — Required** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h9))
- Part: C | Type: heading | Level: 2
- Tags: [must-or-shall, standards_review]
- Score: 0.8818
- **Note**: Marked as "Required"
9-30. [Additional results on specification creation, interface design, collaboration, and developer portals]
---
## Search 5: Design (Mandatory - Part A)
**Query Type**: semantic_search_filtered
**Query**: "design"
**Tags Filter**: ["must-or-shall"]
**Part Filter**: A
**Limit**: 20
**Purpose**: Find existing mandatory design requirements in Part A
### Results (2 items)
1. **Design-driven approach** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part2-section2-para3))
- Part: A | Type: para
- Tags: [definition, definitions, should-or-may, good-practice, must-or-shall, standards_review]
- Content: "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. Taking a design-driven approach simply means that the API design should be performed before development begins — it does not mean that development is hindered in any way."
- Score: 0.8167
- **Note**: Mixed tags suggest elevation discussion
2. **Target application developers** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section1-para5))
- Part: A | Type: para
- Tags: [should-or-may, good-practice, must-or-shall, standards_review]
- 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."
- Score: 0.7810
- **Note**: Strong elevation candidate per annotation
---
## Key Findings Summary
### Mandatory Requirements Found
1. Design-driven approach MUST be taken (Part C) ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para33))
### Strong Elevation Candidates
1. **Design for the consumer** - Foundational principle (Part A)
2. **Design-driven development / Specification-first** - Core process requirement
3. **Co-design with application developers** - Ensures fit for purpose
4. **Business process analysis** - Ensures business-driven vs. technology-driven
### Key Design Principles to Include
1. Design for the consumer (consumer-first mindset)
2. Design-driven development (specification before code)
3. Co-design (collaboration with stakeholders)
4. Dogfooding (internal use validates design)
5. Agility over completeness (iterative approach)
6. Low barrier to entry (sandbox, documentation, SDK)
7. Business-driven not technology-driven
8. Lowest practical granularity
9. Generic not prescriptive (allow innovation)
### API Types Identified
- REST (most common, architectural style, OpenAPI specification)
- GraphQL
- AsyncAPI (event-based)
- gRPC
### External Standards Referenced
- NZ Government Digital Service Design Standard (should influence API design)
- OpenAPI Specification (for REST APIs)
- W3C Standards
---
## Notes for Drafting
1. **Elevation Strategy**: Several "should-or-may" items have annotations suggesting they are "difficult to see how this is not mandatory" - these are prime candidates for elevation
2. **Structure**: Content naturally organizes into:
- Core design principles (consumer-first, design-driven, co-design)
- Design process (specification-first, business analysis, collaboration)
- API type selection (REST primary focus)
3. **Cross-references**: Multiple sections reference each other (Part A principles → Part C implementation)
4. **Balance**: Mix of philosophical principles (design for consumer) and concrete requirements (specification before code)