Chapter 05: Phase 2 API Walk-Through

5.1 Phase 2 in one paragraph

Phase 2 specifies the HTTPS surface for time-series data: write, query, stream, and rollup endpoints. Transport is TLS 1.3 (IETF RFC 8446) only; HTTP/2 RECOMMENDED for multiplexing the high request volumes typical of IoT ingest.

5.2 Discovery

Every host publishes a discovery document at /.well-known/wia-time-series-data listing endpoints, supported signatures, supported aggregations, and rate limits. Discovery responses are cacheable for 300 seconds.

5.3 Write Endpoint

POST /tsd/write
Content-Type: application/json
Idempotency-Key: ...
Authorization: WIA-Sig keyid="...",signature="..."

The write endpoint accepts batched points (typically 1000 points per request to amortise the network round trip). Hosts MUST honour Idempotency-Key per IETF draft idempotency-key-header so devices can safely retry on flaky networks.

5.4 Query Endpoint

POST /tsd/query
Content-Type: application/json

The query endpoint accepts a query envelope (Chapter 4 §4.4) and returns either a stream of points or a single aggregate. For interactive dashboard queries that need sub-second response, hosts SHOULD pre-aggregate via downsampling (Chapter 2 §2.5) so that queries hit pre-computed rollups rather than raw points.

5.5 Stream Endpoint

GET /tsd/stream/{series_id}
Accept: text/event-stream

Server-Sent Events for real-time subscription. Reconnecting clients pass Last-Event-Id per WHATWG HTML §9.2 to resume from the last received event.

5.6 Rollup Endpoint

POST /tsd/rollup

Triggers an explicit rollup as described in Chapter 4 §4.5. Useful when an operator changes a downsampling policy retroactively and needs to backfill rollups for older data.

Summary

Phase 2 is REST conventions plus SSE for streams. The conformance test suite walks every endpoint with mock data so an integrator can verify their implementation before going to production.

Next: Chapter 6 →

Cross-Chapter References

This chapter participates in the WIA-DATA-014 8-chapter survey. Each chapter is intended to be readable standalone, but together they map the full surface of the standard. Chapter 1 sets context, Chapters 2-3 cover modeling and storage trade-offs, Chapters 4-7 walk the four-Phase specification, and Chapter 8 closes with conformance and roadmap.

Where to Look Next

Conformance test suite — https://github.com/WIA-Official/wia-time-series-data-conformance is the single source of truth for what your implementation needs to pass.
Reference container — wia/time-series-data-host:1.0.0 implements every Phase 2 endpoint with mock data; integrators exercise their bridge against it before going to production.
Companion CLI — cli/time-series-data.sh ships sample envelope generators (validate, series, point, query, rollup, info subcommands) so an implementer can produce conformant payloads without hand-rolling JSON.

Implementer Notes

Three operational concerns recur across time-series implementations and are baked into the standard. First, cardinality management: every label dimension multiplies the number of distinct series the host must index, and beyond a few million distinct combinations index lookup latency degrades sharply. The standard recommends declaring per-series cardinality budgets and refusing writes that would push past them. Second, late-arriving points: mobile and edge sensors frequently emit measurements with timestamps in the past after a network outage; the standard requires hosts to accept late points up to a configurable bound (default 24 hours) and trigger a re-rollup. Third, retention policy: every series declares explicit retention bounds and downsampling rules, so capacity planning is not magic and operators can reason about long-term storage cost from the moment they create a series.