Phase 2.1: Systems Methods

[Sam-Bolling]

Task

Implement all 12 Systems methods in url_builder.ts and add Systems method tests to url_builder.spec.ts. Systems is the first Phase 2 resource type and establishes the pattern all subsequent resource type tasks (#6–#13) will follow.

ROADMAP Reference: Phase 2, Task 1 — Systems Methods (~2–2.5 hours implementation + ~0.5 hour testing, Medium complexity)

---

Files to Create or Modify

File	Action	Est. Lines	Purpose
src/ogc-api/csapi/url_builder.ts	Modify	~80–120 added	Add 12 Systems methods with resource validation
src/ogc-api/csapi/url_builder.spec.ts	Modify	~40–50 added	Add Systems method tests

Blueprint Reference

Follow the EDR pattern in src/ogc-api/edr/url_builder.ts (562 lines) — specifically how EDR methods validate resource availability, construct URLs, and append query parameters. Also follow the getSystems() / getDataStreams() examples in the Guide §6 (lines 857–891) which show the exact method pattern: resource validation → URL construction → query string appending.

Scope — What to Implement

12 Systems Methods

Each method validates resource availability (~2 lines), builds a URL using buildResourceUrl(), appends query parameters using buildQueryString(), and returns the constructed URL string.

Collection query:

• getSystems(options?: SystemQueryOptions): string — GET /systems with pagination, filtering, bbox, datetime, sorting

Single resource:

• getSystem(id: string, options?): string — GET /systems/{id}

CRUD operations:

• createSystem(body: object): string — POST /systems
• updateSystem(id: string, body: object): string — PUT /systems/{id}
• deleteSystem(id: string): string — DELETE /systems/{id}

History:

• getSystemHistory(id: string, options?): string — GET /systems/{id}/history

Hierarchical navigation:

• getSystemSubsystems(id: string, options?): string — GET /systems/{id}/subsystems (supports recursive parameter)

Part 2 cross-links:

• getSystemDataStreams(id: string, options?): string — GET /systems/{id}/datastreams
• getSystemControlStreams(id: string, options?): string — GET /systems/{id}/controlstreams

Association links:

• getSystemSamplingFeatures(id: string, options?): string — GET /systems/{id}/samplingFeatures
• getSystemDeployments(id: string, options?): string — GET /systems/{id}/deployments
• getSystemProcedures(id: string, options?): string — GET /systems/{id}/procedures

Systems Query Parameters

Systems supports: bbox, datetime, recursive, parent, deployment, procedure, foi, id, uid, q, property filters, limit, offset, f, sortBy, sortOrder.

All parameters are serialised by the shared buildQueryString() helper (Issue #3). Temporal support: datetime only (no phenomenonTime, resultTime, executionTime, or issueTime — see Guide §6 temporal applicability matrix).

JSDoc Requirements

• Document each method with @param for all parameters, @returns description, and usage example
• Add @see links to OGC CSAPI Part 1 specification sections for Systems endpoints
• Follow the JSDoc style in src/ogc-api/edr/url_builder.ts

Testing Requirements

• Extend src/ogc-api/csapi/url_builder.spec.ts (~40–50 lines)
• Test getSystems with pagination (limit, offset), filtering (id, q), bbox, datetime, sortBy/sortOrder
• Test getSystem with a specific ID
• Test CRUD operations (createSystem, updateSystem, deleteSystem) produce correct URLs
• Test navigation methods (getSystemSubsystems with recursive=true, getSystemDataStreams, getSystemDeployments)
• Test resource validation — calling any Systems method when systems is not in availableResources throws an error
• Test query parameter encoding (bbox comma-separated, datetime ISO 8601)
• Follow test patterns from src/ogc-api/edr/url_builder.spec.ts

Scope — What NOT to Touch

• ❌ Do NOT implement Deployments, Procedures, Sampling Features, Properties, DataStreams, Observations, Control Streams, or Commands methods — those belong to Issues Phase 2.2: Deployments Methods #6–Phase 2.9: Commands Methods #13
• ❌ Do NOT modify model.ts — type definitions belong to Issue Phase 1.1: Create Type System (csapi/model.ts) #1
• ❌ Do NOT modify helpers.ts — helper utilities belong to Issue Phase 1.2: Create Helper Utilities (csapi/helpers.ts) #2
• ❌ Do NOT modify the constructor, buildResourceUrl(), buildQueryString(), extractAvailableResources(), or availableResources — those belong to Issue Phase 1.3: Create Stub QueryBuilder (csapi/url_builder.ts) #3
• ❌ Do NOT modify endpoint.ts, info.ts, or src/index.ts — integration belongs to Issue Phase 1.4: Integrate with OgcApiEndpoint #4
• ❌ Do NOT modify files outside the "Files to Create or Modify" table above
• ❌ Do NOT refactor existing code unless required to complete this task

Acceptance Criteria

• url_builder.ts contains all 12 Systems methods listed above
• Each method validates resource availability before constructing a URL
• Each method uses buildResourceUrl() and buildQueryString() helpers
• All new methods have complete JSDoc documentation with @param, @returns, @see
• url_builder.spec.ts contains Systems tests covering pagination, filtering, bbox, CRUD, navigation, validation, and encoding (~40–50 lines)
• Existing tests still pass (npm test)
• No lint errors

Dependencies

Blocked by: Issue #1 (Type System — provides SystemQueryOptions and resource types), Issue #2 (Helper Utilities — provides encodeBBox, encodeDateTime, encodeArray), Issue #3 (Stub QueryBuilder — provides constructor, buildResourceUrl, buildQueryString, availableResources)
Blocks: Issues #6–#13 (all subsequent resource type methods follow the pattern established here)

---

Operational Constraints

⚠️ MANDATORY: Before starting work on this issue, review docs/governance/AI_OPERATIONAL_CONSTRAINTS.md.

Key constraints for this task:

• Precedence: OGC specifications → AI Collaboration Agreement → This issue description → Existing code → Conversational context
• No scope expansion: Do not infer unstated requirements or add unrequested features
• No refactoring: Do not rename, restructure, or "improve" code outside this issue's scope
• Minimal diffs: Prefer the smallest change that satisfies the acceptance criteria
• Ask when unclear: If intent is ambiguous, stop and ask for clarification

---

References

Read these documents before starting implementation. They are ordered by priority.

Primary References (must read)

#	Document	Section/Lines	What It Provides
1	docs/planning/csapi-implementation-guide.md	§6 Systems Resource Methods (lines 1350–1412)	Full CRUD operations, query parameters, relationship management for Systems
2	docs/planning/csapi-implementation-guide.md	§6 Complete Query Parameter Support (lines 1921–2000)	All query parameters with types, applicability, encoding rules
3	docs/planning/csapi-implementation-guide.md	§6 Query Parameters and Code Reuse (lines 720–900)	Parameter distribution analysis, temporal applicability matrix, buildQueryString code example
4	src/ogc-api/edr/url_builder.ts	Full file (562 lines)	Blueprint: method structure, resource validation, URL construction pattern
5	src/ogc-api/edr/url_builder.spec.ts	Full file	Blueprint: test patterns for URL builder methods
6	docs/planning/ROADMAP.md	Phase 2, Task 1 (lines 147–170)	Authoritative task definition, method list, test requirements

Upstream Type/Import References (files this task imports from)

#	Document	What to Import
7	src/ogc-api/csapi/model.ts	SystemQueryOptions, CSAPIResourceType (created by Issue #1)
8	src/ogc-api/csapi/helpers.ts	Encoding helpers: encodeBBox, encodeDateTime, encodeArray (created by Issue #2)

Research References (context, not required reading)

#	Document	What It Provides
9	docs/research/requirements/csapi-part1-requirements.md	Detailed client implementation requirements for Systems resources
10	docs/research/requirements/csapi-query-parameters.md	Complete catalog of all CSAPI query parameters
11	docs/research/requirements/csapi-subresource-navigation.md	Query parameters on nested endpoints (/systems/{id}/subsystems?recursive=true)
12	docs/research/design/csapiquerybuilder/architecture-decision/results/DECISION-part3-validation.md	47% shared parameters, type-based clustering rationale

Specification References (for @see links and field accuracy)

#	Document	Use
13	OGC API - Connected Systems Part 1 (23-001)	Systems resource definitions, CRUD endpoints, query parameters
14	OGC API - Connected Systems Part 1: OpenAPI Spec	Systems endpoint definitions — normative URL paths
15	SOSA/SSN Ontology	Semantic definitions for system types (sosa:Sensor, sosa:Actuator, sosa:Platform)
16	RFC 7946 (GeoJSON)	Format for encoding Systems as GeoJSON Features
17	OGC API - Connected Systems Part 2 (23-002)	DataStreams/ControlStreams references for cross-link methods

Convention Quick Reference

Rule	Example
Use .js extension for relative imports	import { X } from './file.js'
Use import type for interfaces/types	import type { Y } from './model.js'
Three-tier hierarchy: import from lower tiers only	shared → ogc-api → csapi
Named exports for types and utilities	export interface Z { ... }
as const arrays for enum-like values	export const XTypes = [...] as const
HTTP mocking: globalThis.fetch = jest.fn()	Never use nock, msw, or other libraries
Meaningful tests only	Verify behavior, not that code runs without throwing