Definitions 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: Definitions Research
---
# Definitions Research Results
**Phase**: Key API Terms and Definitions
**Total Searches**: 3
**Total Results**: ~107 results
**Date**: 2025-11-03
## Search Queries Executed
1. `semantic_search_filtered: tags=["definition"], query="definitions"` (limit: 100, returned 12)
2. `semantic_search: "API terminology glossary concepts"` (limit: 50)
3. `semantic_search_balanced: "key API terms and definitions"` (total_limit: 50, min_per_part: 15, returned 45)
---
## Search 1: Definitions with Definition Tag
**Query**: `semantic_search_filtered: tags=["definition"], query="definitions"`
**Results**: 12
**Purpose**: Find formally defined terms with definition tags
### Key Results
1. **Glossary of terms** (Part A) - Score: 0.853
- Content: 7. Glossary of terms ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part7-title))
- Tags: definition, definitions
2. **Glossary of terms** (Part B) - Score: 0.851
- Content: 14. Glossary of terms ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part14-title))
- Tags: definition, definitions
3. **Glossary of acronyms** (Part A) - Score: 0.821
- Content: 8. Glossary of acronyms ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part8-title))
- Tags: definition, definitions
### Key Finding
**Critical Resources Identified:**
- Part A has a comprehensive glossary of terms (section 7)
- Part B has a comprehensive glossary of terms (section 14)
- Part A has a glossary of acronyms (section 8)
- These should be primary sources for Appendix D: Glossary
---
## Search 2: API Terminology, Glossary, Concepts
**Query**: `semantic_search: "API terminology glossary concepts"`
**Results**: 50
**Purpose**: Comprehensive search for API terminology and concepts
### Top Results
1. **API concepts** (Part A) - Score: 0.921
- Content: 1. API concepts ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-title))
2. **Definitions for APIs covered in guidelines** (Part B) - Score: 0.893
- Content: 1.2. Definitions for APIs covered in these guidelines ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section2-title))
- Tags: definition, definitions
3. **API concepts and management** (Part A) - Score: 0.872
- Content: API guidelines — Part A: API concepts and management 2022 ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#h1))
4. **Categorisation of APIs** (Part A) - Score: 0.872
- Content: 3.2. Categorisation of APIs ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-section2-title))
- Tags: should-or-may, standards_review
5. **What is an API** (Part A) - Score: 0.871
- Content: An API is a computing interface that defines a shared boundary across which 2 or more components exchange information. In practice, an API is generally a piece of software that provides a way for other disparate pieces of software (applications, systems) to talk to one another. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section2-para1))
- Tags: definition, definitions
6. **API definition glossary** (Part B) - Score: 0.865
- Content: ==API (Application Programming Interface)== An API is a piece of software that provides a way for other disparate pieces of software (applications, systems) to talk to one another. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part14-para1-l2))
- Tags: definition, definitions
7. **API definition glossary** (Part A) - Score: 0.865
- Content: ==API (Application Programming Interface)== An API is a piece of software that provides a way for other disparate pieces of software (applications, systems) to talk to one another. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part7-para1-l2))
- Tags: definition, definitions
8. **API definition glossary** (Part C) - Score: 0.865
- Content: ==API (Application Programming Interface)== An API is a piece of software that provides a way for other disparate pieces of software (applications, systems) to talk to one another. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part8-para1-l2))
- Tags: definition, definitions
9. **Glossary of terms** (Part A) - Score: 0.861
- Content: 7. Glossary of terms ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part7-title))
- Tags: definition, definitions
10. **Common categories of API** (Part A) - Score: 0.860
- Content: APIs are commonly categorised as shown in table 1: ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section2-para2))
- Tags: definition, definitions
### Key Terms Identified
**Core API Concepts:**
- API (Application Programming Interface)
- Internal API
- External API
- Partner API
- Public/Open API
- System API
- Process API
- Experience API
**API Components:**
- API developer
- API developer portal
- API gateway
- API manager
- API catalogue
- API consumer
- API provider
- Application developer
- Consuming application
**Technical Terms:**
- Interface specification
- REST (Representational State Transfer)
- GraphQL
- AsyncAPI
- gRPC
- OpenAPI Specification
- HTTP verbs (GET, POST, PUT, DELETE)
- Resource
- Endpoint
**Security Terms:**
- Authentication
- Authorization
- OAuth 2.0
- OpenID Connect
- API key
- Access token
- TLS (Transport Layer Security)
**Operations Terms:**
- Analytics
- Monitoring
- SLA (Service Level Agreement)
- Throttling
- Quota
- Deprecation
- Versioning
---
## Search 3: Key API Terms and Definitions (Balanced)
**Query**: `semantic_search_balanced: "key API terms and definitions"`
**Results**: 45 (balanced across Parts A, B, C)
**Purpose**: Ensure balanced representation of definitions from all parts
### Top Results by Part
**Part B (Security Focus):**
1. **API key** - Score: 0.909
- Content: **API key** ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-para7-tb1-tr5-td1-l1))
2. **API key definition** - Score: 0.905
- Content: **API key** A 40+ random character string used in some scenarios to authenticate the client application to the API. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part9-para7-tb1-tr5-td1))
3. **API key authentication** - Score: 0.891
- Content: API keys are a digital authentication mechanism, with the API key taking the form of a long string of generated characters. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part7-section3-para1))
4. **Definitions for APIs** - Score: 0.882
- Content: 1.2. Definitions for APIs covered in these guidelines ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partb/2022/en/#part1-section2-title))
- Tags: definition, definitions
**Part A (Concepts):**
1. **Key characteristics** - Score: 0.878
- Content: 3. Key characteristics of an API ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part3-title))
- Tags: definition, definitions
2. **API concepts** - Score: 0.872
- Content: 1. API concepts ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-title))
3. **What is an API** - Score: 0.863
- Content: 1.2. What is an API ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part1-section2-title))
4. **API definition** - Score: 0.861
- Content: ==API (Application Programming Interface)== An API is a piece of software that provides a way for other disparate pieces of software (applications, systems) to talk to one another. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-parta/2022/en/#part7-para1-l2))
- Tags: definition, definitions
**Part C (Development):**
1. **API Key Header** - Score: 0.896
- Content: {API Key Header} ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb1-tr5-td1-l1))
2. **API Key Header usage** - Score: 0.883
- Content: {API Key Header} Note: there is no set naming standard for an API Key Header ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section6-tb1-tr5-td1))
3. **API definition** - Score: 0.861
- Content: ==API (Application Programming Interface)== An API is a piece of software that provides a way for other disparate pieces of software (applications, systems) to talk to one another. ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part8-para1-l2))
- Tags: definition, definitions
4. **Types of API** - Score: 0.859
- Content: Table 1: Types of API ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-para6-tb1-caption))
- Tags: definition, definitions
5. **Types of API section** - Score: 0.859
- Content: 1.2.2. Types of API ([DocRef](https://docref.digital.govt.nz/nz/dia-apis-partc/2022/en/#part1-section2-h2))
- Tags: definition, definitions
### Key Findings
**Balanced Coverage:**
- Part A provides foundational concepts and categorization
- Part B provides security-focused definitions (API keys, authentication)
- Part C provides development-focused definitions (headers, types, implementation)
---
## Comprehensive Term List for Glossary
Based on all three searches, the following terms should be included in the Definitions section and Appendix D:
### Core API Terms
1. **API (Application Programming Interface)**
- Definition: A piece of software that provides a way for other disparate pieces of software (applications, systems) to talk to one another
- Source: All parts (A, B, C glossaries)
2. **Internal API**
- Definition: An API that is used solely within your organisation by known internal personnel
- Source: Part A, Table 1
3. **External API**
- Definition: An API that is used by customers and/or application developers outside your organisation
- Source: Part A, Table 1
4. **Partner API**
- Definition: An API used by business partners with special contractual relationship
- Source: Part A, Table 1
5. **Public/Open API**
- Definition: An API used by anyone who can meet access control requirements
- Source: Part A, Table 1
6. **System API**
- Definition: APIs that unlock data held in legacy systems or deliver access to backend functions
- Source: Part A, section 3.2
7. **Process API**
- Definition: APIs that create business value by breaking down silos across system APIs
- Source: Part A, section 3.2
8. **Experience API**
- Definition: APIs that target user experience, commonly exposed to external consumers
- Source: Part A, section 3.2
### API Components
9. **API Developer**
- Definition: The organisation or person who creates the API and maintains interface specification
- Source: Part A, B, C glossaries
10. **API Developer Portal**
- Definition: Component allowing API providers to engage with, onboard, educate and manage application developers
- Source: Part A, B, C glossaries
11. **API Gateway**
- Definition: The means through which APIs are offered to the outside world; hosts APIs for consumer access
- Source: Part A, section 5.1.2
12. **API Manager**
- Definition: Technical layer enabling agency to control API visibility and behaviour
- Source: Part A, B, C glossaries
13. **API Catalogue**
- Definition: List of all APIs offered with interface specifications and access guidance
- Source: Part A, section 4.2
14. **API Consumer**
- Definition: Application developers, consuming applications, and customers using APIs
- Source: Part A, section 1.3
15. **API Provider**
- Definition: Organization (e.g., government agency) that owns resources exposed by the API
- Source: Part A, section 1.3
16. **Application Developer**
- Definition: Person/organization creating software that uses APIs
- Source: Part A, section 1.3
17. **Consuming Application**
- Definition: Software created by application developers that uses APIs to access resources
- Source: Part A, section 1.3
### Technical Terms
18. **Interface Specification**
- Definition: Technical description and reference model for an API
- Source: Part A, section 3.1
19. **REST (Representational State Transfer)**
- Definition: Architectural style for designing networked applications
- Source: Part C, section 1.2.2
20. **HTTP Verbs**
- Definition: Standard methods (GET, POST, PUT, DELETE) for API operations
- Source: Part C, section 1.4
21. **Resource**
- Definition: Information or functionality accessible through an API
- Source: Part C, section 1.2
22. **Endpoint**
- Definition: Specific URI where an API resource can be accessed
- Source: Part C
23. **OpenAPI Specification**
- Definition: Standard, programming language-agnostic interface to REST APIs
- Source: Part C, section 1.2
### Security Terms
24. **Authentication**
- Definition: Process of verifying the identity of a user or application
- Source: Part B, section 1.1
25. **Authorization**
- Definition: Process of determining what an authenticated user/application is allowed to do
- Source: Part B, section 1.1
26. **OAuth 2.0**
- Definition: Industry-standard protocol for authorization
- Source: Part B, section 2
27. **OpenID Connect**
- Definition: Identity layer on top of OAuth 2.0 for authentication
- Source: Part B, section 2
28. **API Key**
- Definition: 40+ random character string used to authenticate client application to API
- Source: Part B, section 7.3
29. **Access Token**
- Definition: Credential used to access protected resources
- Source: Part B, OAuth sections
30. **TLS (Transport Layer Security)**
- Definition: Cryptographic protocol for secure communications
- Source: Part B, section 11
### Operations Terms
31. **Analytics**
- Definition: The capturing and reporting of API usage
- Source: Part A, B, C glossaries
32. **Monitoring**
- Definition: Tracking API usage, performance, and security events
- Source: Part B, section 1.4
33. **SLA (Service Level Agreement)**
- Definition: Agreement defining performance, availability metrics
- Source: Part A, B, C glossaries
34. **Throttling**
- Definition: Rate limiting to ensure all consumers can access API within SLA bounds
- Source: Part A, section 4.3
35. **Quota**
- Definition: Limited access (e.g., set number of calls per hour) to protect API from abuse
- Source: Part A, section 4.3
36. **Deprecation**
- Definition: Process of retiring an old API version
- Source: Part A, section 2.6
37. **Versioning**
- Definition: Managing different versions of an API
- Source: Part A, section 2.6; Part C, section 1.10
### Lifecycle Terms
38. **Service Design**
- Definition: Phase including consumer management, service level management, API design
- Source: Part A, Figure 7
39. **Service Transition**
- Definition: Phase including development, testing, catalogue, release management
- Source: Part A, Figure 7
40. **Service Operation**
- Definition: Phase including access management, support, incident management
- Source: Part A, Figure 7
41. **Continual Service Improvement**
- Definition: Ongoing process to ensure APIs run optimally and adapt to changing demand
- Source: Part A, section 4.4
---
## Acronyms List
From Part A, section 8 (Glossary of acronyms):
- **API**: Application Programming Interface
- **HTTP**: Hypertext Transfer Protocol
- **HTTPS**: HTTP Secure
- **JSON**: JavaScript Object Notation
- **JWT**: JSON Web Token
- **OAuth**: Open Authorization
- **OIDC**: OpenID Connect
- **REST**: Representational State Transfer
- **SLA**: Service Level Agreement
- **SSL**: Secure Sockets Layer
- **TLS**: Transport Layer Security
- **URI**: Uniform Resource Identifier
- **URL**: Uniform Resource Locator
- **XML**: Extensible Markup Language
- **YAML**: YAML Ain't Markup Language
---
## Additional Definitions to Source
The following should be extracted from the full glossaries:
**From Part A, Section 7:**
- Complete glossary of terms
**From Part B, Section 14:**
- Complete glossary of terms (likely focused on security)
**From Part A, Section 8:**
- Complete glossary of acronyms
These glossaries should be read directly when drafting Appendix D.
---
## Cross-References to Other Research Files
**Related to Security Phase:**
- Authentication terms (OAuth 2.0, OpenID Connect, API keys)
- Authorization concepts
- TLS/SSL definitions
**Related to Development Phase:**
- REST terminology
- HTTP verbs
- Interface specifications
- OpenAPI
**Related to Deployment Phase:**
- Versioning concepts
- API catalogue
- Gateway definitions
**Related to Operations Phase:**
- Analytics
- Monitoring
- SLA
- Throttling and quota
- Deprecation
**Related to Design Phase:**
- API categorization (System, Process, Experience)
- API types (Internal, External, Partner, Public)
- Design principles
---
## Notes for Drafting
1. **Appendix D: Glossary Structure**
- Should be alphabetically organized
- Each term should have: definition, source citation(s), related terms
- Consider grouping related terms or using cross-references
2. **Definitions in Main Body**
- First use of each term should reference Appendix D
- Key terms should be defined in context where first introduced
- Maintain consistency with glossary definitions
3. **Citation Strategy**
- If same term defined in multiple parts, cite all sources
- Prefer Part B definitions for security terms
- Prefer Part C definitions for development terms
- Prefer Part A definitions for conceptual terms
---
## Total Results by Part
- **Part A**: ~40 results (foundational concepts, management, lifecycle)
- **Part B**: ~35 results (security focus, technical specifications)
- **Part C**: ~32 results (development, implementation guidance)
**Note**: Balanced representation achieved through semantic_search_balanced query.