Skip to content

Commit 333821e

Browse files
thibauultthibauult
authored
feat: Add 28 missing resource endpoints from Hue CLIP API v2 (#41)
1 parent e8201b3 commit 333821e

File tree

114 files changed

+5240
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

114 files changed

+5240
-0
lines changed

‎AGENTS.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to WARP (warp.dev) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
OpenHue is an OpenAPI 3.0.3 specification for the Philips Hue CLIP (Connected Lighting Interface Protocol) API v2. This repository does not contain application code—it consists entirely of YAML files defining the API specification.
8+
9+
## Build & Development Commands
10+
11+
```bash
12+
make setup # Install Redocly CLI globally via npm
13+
make verify # Lint and validate the OpenAPI specification
14+
make build # Bundle specification into build/openhue.yaml
15+
make docs # Generate static HTML documentation in build/
16+
make clean # Remove the build/ directory
17+
make help # List all available make targets
18+
```
19+
20+
Alternatively, use Redocly CLI directly:
21+
```bash
22+
redocly lint # Validate specification
23+
redocly bundle src/main.yaml -o out.yaml # Bundle to single file
24+
redocly build-docs -o out.html # Generate docs
25+
```
26+
27+
## Architecture
28+
29+
### Entry Point
30+
- `src/main.yaml` - Root OpenAPI specification defining paths, tags, servers, and security schemes
31+
32+
### Directory Structure
33+
Each Hue API resource has its own directory under `src/`:
34+
```
35+
src/{resource}/
36+
├── {resource}.yaml # Collection endpoint (GET all, POST)
37+
├── {resource}_{id}.yaml # Item endpoint (GET/PUT/DELETE by ID)
38+
└── schemas/ # Resource-specific schemas
39+
```
40+
41+
Resources: `auth`, `bridge`, `bridge_home`, `device`, `device_power`, `grouped_light`, `light`, `light_level`, `motion`, `resource`, `room`, `scene`, `smart_scene`, `temperature`, `zone`
42+
43+
### Shared Components
44+
- `src/common/` - Reusable schemas (ApiResponse, error responses, Brightness, Color, Dimming, etc.)
45+
46+
### Testing
47+
- `http/` - IntelliJ HTTP Client files for manual endpoint testing
48+
- Requires `http/http-client.private.env.json` with your bridge's apiKey and baseUrl
49+
50+
## Specification Conventions
51+
52+
- OpenAPI version: 3.0.3
53+
- Authentication: `hue-application-key` header (API key)
54+
- All paths reference external YAML files via `$ref`
55+
- Error responses defined in `src/common/error.yaml` and reused across endpoints
56+
57+
## Code Style
58+
59+
- 2-space indentation (YAML)
60+
- LF line endings
61+
- Trailing newline required
62+
- Trim trailing whitespace

‎src/behavior_instance/behavior_instance.yaml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
get:
2+
operationId: getBehaviorInstances
3+
summary: List behavior instance.
4+
description: List all available behavior instance resources.
5+
tags:
6+
- BehaviorInstance
7+
security:
8+
- HueApplicationKey: [ ]
9+
responses:
10+
200:
11+
description: BehaviorInstance Success Response
12+
content:
13+
application/json:
14+
schema:
15+
allOf:
16+
- $ref: '../common/ApiResponse.yaml'
17+
- type: object
18+
properties:
19+
data:
20+
type: array
21+
items:
22+
$ref: './schemas/BehaviorInstanceGet.yaml'
23+
401:
24+
$ref: '../common/error.yaml#/components/responses/Unauthorized'
25+
403:
26+
$ref: '../common/error.yaml#/components/responses/Forbidden'
27+
404:
28+
$ref: '../common/error.yaml#/components/responses/NotFound'
29+
405:
30+
$ref: '../common/error.yaml#/components/responses/MethodNotAllowed'
31+
406:
32+
$ref: '../common/error.yaml#/components/responses/NotAcceptable'
33+
409:
34+
$ref: '../common/error.yaml#/components/responses/Conflict'
35+
429:
36+
$ref: '../common/error.yaml#/components/responses/TooManyRequests'
37+
500:
38+
$ref: '../common/error.yaml#/components/responses/InternalServerError'
39+
503:
40+
$ref: '../common/error.yaml#/components/responses/ServiceUnavailable'
41+
507:
42+
$ref: '../common/error.yaml#/components/responses/InsufficientStorage'

‎src/behavior_instance/behavior_instance_{behaviorInstanceId}.yaml‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
get:
2+
operationId: getBehaviorInstance
3+
summary: Get behavior instance.
4+
description: Get details of a single behavior instance resource from its given `{behaviorInstanceId}`.
5+
tags:
6+
- BehaviorInstance
7+
security:
8+
- HueApplicationKey: [ ]
9+
parameters:
10+
- name: behaviorInstanceId
11+
in: path
12+
schema:
13+
type: string
14+
required: true
15+
description: ID of the behavior instance
16+
responses:
17+
200:
18+
description: BehaviorInstance Success Response
19+
content:
20+
application/json:
21+
schema:
22+
allOf:
23+
- $ref: '../common/ApiResponse.yaml'
24+
- type: object
25+
properties:
26+
data:
27+
type: array
28+
items:
29+
$ref: './schemas/BehaviorInstanceGet.yaml'
30+
401:
31+
$ref: '../common/error.yaml#/components/responses/Unauthorized'
32+
403:
33+
$ref: '../common/error.yaml#/components/responses/Forbidden'
34+
404:
35+
$ref: '../common/error.yaml#/components/responses/NotFound'
36+
405:
37+
$ref: '../common/error.yaml#/components/responses/MethodNotAllowed'
38+
406:
39+
$ref: '../common/error.yaml#/components/responses/NotAcceptable'
40+
409:
41+
$ref: '../common/error.yaml#/components/responses/Conflict'
42+
429:
43+
$ref: '../common/error.yaml#/components/responses/TooManyRequests'
44+
500:
45+
$ref: '../common/error.yaml#/components/responses/InternalServerError'
46+
503:
47+
$ref: '../common/error.yaml#/components/responses/ServiceUnavailable'
48+
507:
49+
$ref: '../common/error.yaml#/components/responses/InsufficientStorage'
50+
put:
51+
operationId: updateBehaviorInstance
52+
summary: Update behavior instance.
53+
description: Update a single behavior instance resource from its given `{behaviorInstanceId}`.
54+
tags:
55+
- BehaviorInstance
56+
security:
57+
- HueApplicationKey: [ ]
58+
parameters:
59+
- name: behaviorInstanceId
60+
in: path
61+
schema:
62+
type: string
63+
required: true
64+
description: ID of the behavior instance
65+
requestBody:
66+
content:
67+
application/json:
68+
schema:
69+
$ref: './schemas/BehaviorInstancePut.yaml'
70+
responses:
71+
200:
72+
description: Success
73+
content:
74+
application/json:
75+
schema:
76+
allOf:
77+
- $ref: '../common/ApiResponse.yaml'
78+
- type: object
79+
properties:
80+
data:
81+
type: array
82+
items:
83+
$ref: '../common/ResourceIdentifier.yaml'
84+
401:
85+
$ref: '../common/error.yaml#/components/responses/Unauthorized'
86+
403:
87+
$ref: '../common/error.yaml#/components/responses/Forbidden'
88+
404:
89+
$ref: '../common/error.yaml#/components/responses/NotFound'
90+
405:
91+
$ref: '../common/error.yaml#/components/responses/MethodNotAllowed'
92+
406:
93+
$ref: '../common/error.yaml#/components/responses/NotAcceptable'
94+
409:
95+
$ref: '../common/error.yaml#/components/responses/Conflict'
96+
429:
97+
$ref: '../common/error.yaml#/components/responses/TooManyRequests'
98+
500:
99+
$ref: '../common/error.yaml#/components/responses/InternalServerError'
100+
503:
101+
$ref: '../common/error.yaml#/components/responses/ServiceUnavailable'
102+
507:
103+
$ref: '../common/error.yaml#/components/responses/InsufficientStorage'

‎src/behavior_instance/schemas/BehaviorInstanceGet.yaml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
type: object
2+
allOf:
3+
- $ref: '../../common/Resource.yaml'
4+
- type: object
5+
properties:
6+
script_id:
7+
type: string
8+
description: ID of the behavior script this instance is running.
9+
enabled:
10+
type: boolean
11+
description: True if the behavior instance is enabled.
12+
state:
13+
type: object
14+
description: Current state of the behavior instance.
15+
configuration:
16+
type: object
17+
description: Configuration for this behavior instance.
18+
dependees:
19+
type: array
20+
items:
21+
$ref: '../../common/ResourceIdentifier.yaml'
22+
status:
23+
type: string
24+
enum:
25+
- initializing
26+
- running
27+
- disabled
28+
- errored
29+
last_error:
30+
type: string
31+
description: Last error message if status is errored.
32+
metadata:
33+
type: object
34+
properties:
35+
name:
36+
type: string

‎src/behavior_instance/schemas/BehaviorInstancePut.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
type: object
2+
properties:
3+
type:
4+
type: string
5+
description: Type of the supported resources (always `behavior_instance` here)
6+
enabled:
7+
type: boolean
8+
description: True to enable the behavior instance.
9+
configuration:
10+
type: object
11+
description: Configuration for this behavior instance.
12+
metadata:
13+
type: object
14+
properties:
15+
name:
16+
type: string

‎src/behavior_script/behavior_script.yaml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
get:
2+
operationId: getBehaviorScripts
3+
summary: List behavior script.
4+
description: List all available behavior script resources.
5+
tags:
6+
- BehaviorScript
7+
security:
8+
- HueApplicationKey: [ ]
9+
responses:
10+
200:
11+
description: BehaviorScript Success Response
12+
content:
13+
application/json:
14+
schema:
15+
allOf:
16+
- $ref: '../common/ApiResponse.yaml'
17+
- type: object
18+
properties:
19+
data:
20+
type: array
21+
items:
22+
$ref: './schemas/BehaviorScriptGet.yaml'
23+
401:
24+
$ref: '../common/error.yaml#/components/responses/Unauthorized'
25+
403:
26+
$ref: '../common/error.yaml#/components/responses/Forbidden'
27+
404:
28+
$ref: '../common/error.yaml#/components/responses/NotFound'
29+
405:
30+
$ref: '../common/error.yaml#/components/responses/MethodNotAllowed'
31+
406:
32+
$ref: '../common/error.yaml#/components/responses/NotAcceptable'
33+
409:
34+
$ref: '../common/error.yaml#/components/responses/Conflict'
35+
429:
36+
$ref: '../common/error.yaml#/components/responses/TooManyRequests'
37+
500:
38+
$ref: '../common/error.yaml#/components/responses/InternalServerError'
39+
503:
40+
$ref: '../common/error.yaml#/components/responses/ServiceUnavailable'
41+
507:
42+
$ref: '../common/error.yaml#/components/responses/InsufficientStorage'

0 commit comments

Comments
 (0)