Added the eventstream API endpoint

[flrgh]

👋

This is an attempt to add a spec for the eventstream API, which can send an SSE streaming response or a singular JSON payload.

This API is documented rather sparingly, so it's difficult to fully spec it out. The bit about If-None-Match was reverse engineered through trial and error.

I couldn't figure out how to properly spec out SSE responses in OpenAPI (maybe it's just not possible in 3.0.x?), but I've done my best. The example I included is a snippet of text from a real endpoint with curl, which I think is most helpful to readers. The linter complains about this being a string and therefore not matching the schema, but I have left it as-is and added an ignore rule.

Summary by CodeRabbit

New Features

• Added Event API endpoint (/eventstream/clip/v2) for device events
• Added streaming support with long-polling and incremental delivery capabilities
• Supports multiple response formats: JSON array and text/event-stream
• Added standardized error handling across the Event API

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces a new EventStream API endpoint for fetching device events with streaming and long-polling capabilities, including the OpenAPI operation definition, reusable Event schema with nested structures, and integration into the main API specification.

Changes

Cohort / File(s)	Summary
Lint Configuration .redocly.lint-ignore.yaml	Updated documentation URL and added ignore rule suppressing no-invalid-media-type-examples for the text/event-stream 200 response in the EventStream API.
EventStream API Definition src/eventstream/eventstream.yaml	Added GET /eventstream/clip/v2 operation with If-None-Match header, dual-format responses (JSON array and text/event-stream), and multiple error responses (401, 403, 404, 405, 406, 409, 429, 500, 503, 507).
EventStream Schema src/eventstream/schemas/Event.yaml	Introduced Event schema defining event objects with id (UUID), type (add/delete/error/update enum), creationtime (datetime), and data (array of affected resources with Resource composition).
Main API Integration src/main.yaml	Added Event API tag and registered /eventstream/clip/v2 endpoint referencing the new EventStream operation definition.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Hop along, new stream's arrived,
EventStream API comes alive!
With schemas neat and errors caught,
Device events the data brought.
Long-polling dreams and streaming flows—
Watch your events as knowledge grows! 📊✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Added the eventstream API endpoint' directly and clearly summarizes the main change: introduction of a new eventstream API endpoint with complete specification including schemas, operations, and configuration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[thibauult]

Hey @flrgh, thanks for your first contribution to the project! 🎉

This is a great idea. You're right that SSE support in OpenAPI is a bit tricky, it's not officially part of the 3.0.x spec yet (the OAI is still working on it: https://spec.openapis.org/registry/media-type/sse). That said, I think this addition makes absolute sense for the openhue-api project, as documenting the eventstream endpoint will be valuable for users even if the spec tooling isn't fully there yet.

I'm happy to merge this and ship it in the next release. Thanks again for the effort, especially the reverse engineering work on the If-None-Match behavior! 👏