Update API Docs mirror to the latest version (#1924)

# API Documentation Changelog

## Overview
This document details all changes made to `docs/api/index.html` in the
v2/apiDocs branch compared to v2/main.

---

## 1. Library and Resource Updates

### jQuery Library Versions
- **Old**: `jquery-1.10.2.js` and `jquery-1.10.2-ui.js`
- **New**: `jquery.min.js` and `jquery-ui.min.js`
- **Impact**: Updated to minified versions for better performance

### Stylesheet and Resource Links
- Normalized self-closing tags: `/>` → `>`
- Updated HTTP charset: `utf-8` → `windows-1252` (in meta tag)

---

## 2. HTML Formatting and Encoding Changes

### HTML Entity Encoding
All HTML entity-encoded quotes converted to literal quotes throughout
JSON examples:
- `"` → `"`
- Applied consistently across all JSON sample values in the
documentation

### Self-Closing Tag Normalization
- `<br/>` → `<br>`
- `<link ... />` → `<link ... >`
- Applied to all HTML elements in the documentation

### Table Structure
- Added `<tbody>` tags to all table elements for proper HTML structure
- Added `style="display: none;"` attributes to hidden rows for cleaner
display

---

## 3. API Test Links

### URL Updates
All test operation links now use absolute URLs instead of relative
paths:
- **Old**: `href="doc/test/[hash]"`
- **New**:
`href="https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/doc/test/[hash]"`

### Affected Operations
Applied to all API operations that include test links:
- Create action group
- Update action group
- Delete action group
- Get action groups
- Execute action group
- And all other endpoints with test functionality

---

## 4. Access Scope Information

### New Access Scope Blocks
Added `<pre class="scoped">Access scope : ...</pre>` blocks to API
operations:
- Full enduser API access (enduser/*)
- Enduser Open API (enduser/o)
- Applied to all applicable API endpoints

### Example
```html
<pre class="scoped">Access scope : Full enduser API access (enduser/*)</pre>
```

---

## 5. Sample JSON and Default Values

### Action Group Examples

#### shortcut Field
- **Old**: `"shortcut" : false`
- **New**: `"shortcut" : true`

#### notificationCondition Field
- **Old**: `"notificationCondition" : "ALWAYS"`
- **New**: `"notificationCondition" : "ON_SUCCESS"`

#### New Field: lockLevel
- **Added**: `"lockLevel" : 5` to command parameters
- **Location**: Command examples within action groups

### Example Before:
```json
{
  "shortcut" : false,
  "notificationCondition" : "ALWAYS",
  "commands" : [ {
    "delay" : 1
  } ]
}
```

### Example After:
```json
{
  "shortcut" : true,
  "notificationCondition" : "ON_SUCCESS",
  "commands" : [ {
    "delay" : 1,
    "lockLevel" : 5
  } ]
}
```

---

## 6. Event Information Updates

### Event Descriptions and Reordering

#### GatewaySynchronizationStartedEvent
- **Added Fields**:
  - `"owningPartner" : "an owning partner"`
  - `"gatewayId" : "A gateway id (ex: 0101-1234-5678)"`

#### GatewaySynchronizationEndedEvent
- **Added Fields**:
  - `"owningPartner" : "an owning partner"`
  - `"gatewayId" : "A gateway id (ex: 0101-1234-5678)"`

#### ActionGroupCreatedEvent
- **Reordered**: Event appears later in documentation (moved after
GatewaySynchronizationStartedEvent)
- **Added Fields**:
  - `"owningPartners" : [ "some owning partners" ]`
- **Modified Structure**: Updated JSON example to reflect current API
response format

#### ActionGroupUpdatedEvent
- **New Event**: Added to documentation
- **Fields Include**:
  - `"owningPartners" : [ "some owning partners" ]`
  - Full action group structure with metadata

#### ActionGroupDeletedEvent
- **New Event**: Added to documentation
- **Fields Include**:
  - `"owningPartners" : [ "some owning partners" ]`
  - `"actionGroupOID"`
  - `"setupOID"`

#### ExecutionStateChangedEvent
- **Enhanced Fields**:
  - Added `"owningPartners" : [ "some owning partners" ]`
  - Added `"failedCommands"` array with detailed error information
  - Added `"failureTypeCode"` and `"failureType"` fields

#### DeviceStateChangedEvent
- **Enhanced Fields**:
  - Added `"owningPartners" : [ "some owning partners" ]`
  - Updated device state change structure

---

## 7. API Response Examples Updates

### Action Group Response Structure

#### Enhanced Fields
- **creationTime**: `"creationTime" : 1769503155441` (timestamp added)
- **lastUpdateTime**: `"lastUpdateTime" : 1769503155441` (timestamp
added)
- **lockLevel**: `"lockLevel" : 5` (now included in command examples)

### Execution Response Structure
- Updated to include complete execution details
- Added fields: `startTime`, `owner`, `actionGroup`, `description`,
`executionType`, `executionSubType`

---

## 8. Rate Limiting Information

### Updated Rate Limit Blocks
Rate limiting sections now include more detailed information:
- Per-session rate limits with specific time periods
- Categorized limits (e.g., "bulk-load", "exec")

### Example
```html
<pre class="rateLimited">Per-session rate-limit : 1 calls per 1d period for this particular operation (bulk-load)</pre>
```

---

## 9. Parameter Updates

### New Request Parameters
- **preventLockLevelReset**: Added to action group update operations
  - Type: Boolean (default false)
  - Description: "Do not reset command lock levels"

### Enhanced Parameter Descriptions
- Descriptions now wrapped in `<pre>` tags for consistency
- Added optional parameter indicators
- More detailed documentation of parameter purposes

---

## 10. Event Field Documentation

### New Event Fields Documented

#### owningPartner (singular)
- **Type**: String
- **Description**: "Owning partner of the parent entity (gateway, setup
group, ...)) . only available in event streams"
- **Applied to**: GatewaySynchronizationStartedEvent,
GatewaySynchronizationEndedEvent

#### owningPartners (plural)
- **Type**: Array of Strings
- **Description**: "Owning partners of the parent entity (setup, ...)) .
only available in event streams"
- **Applied to**: ActionGroupCreatedEvent, ActionGroupUpdatedEvent,
ActionGroupDeletedEvent, ExecutionStateChangedEvent,
DeviceStateChangedEvent

#### gatewayId
- **Type**: String
- **Description**: "A gateway id (ex: 0101-1234-5678)"
- **Applied to**: Gateway-related events

---

## 11. Content Organization Changes

### Event Reordering
Events are now organized in a different order within the documentation:
1. **Create Action Group Operation**:
   - GatewaySynchronizationStartedEvent (moved first)
   - ActionGroupCreatedEvent
   - GatewaySynchronizationEndedEvent

2. **Update Action Group Operation**:
   - GatewaySynchronizationStartedEvent
   - GatewaySynchronizationEndedEvent
   - ActionGroupUpdatedEvent

3. **Delete Action Group Operation**:
   - GatewaySynchronizationEndedEvent
   - GatewaySynchronizationStartedEvent
   - ActionGroupDeletedEvent

---

## 12. Trigger and Execution Documentation

### Delayed Execution Events
- Enhanced documentation for `DelayedTriggerSetEvent`
- Enhanced documentation for `DelayedTriggerCancelledEvent`
- Clearer execution type descriptions

### Weekly Planning
- Updated examples for weekly planning triggers
- Time-based trigger documentation
- Dawn/dusk trigger clarification

---

## 13. Country Data Updates

### New Country Support
- **Country**: South Korea
- **Code**: KR
- Added to all supported countries lists in location-related API
operations

---

## Summary of Changes

| Category | Change Type | Count |
|----------|------------|-------|
| Library Updates | Version upgrades | 2 |
| HTML Encoding | Entity encoding → literal | ~500+ |
| Self-closing Tags | Normalization | ~200+ |
| Test Links | URL updates | ~100+ |
| Access Scopes | Added blocks | ~50+ |
| Event Fields | New fields | 15+ |
| Event Events | New/reordered | 10+ |
| Sample Values | Updated defaults | 10+ |
| Parameters | New parameters | 5+ |
| Countries | New entries | 1+ |

---

## Impact Assessment

### For API Users
- ✅ Test links now direct to full absolute URLs
- ✅ Better documentation of event ownership and access scopes
- ✅ New fields provide more context (owningPartner/owningPartners)
- ✅ Enhanced error information in ExecutionStateChangedEvent

### For HTML/Browser Rendering
- ✅ Proper `<tbody>` tags improve semantic HTML
- ✅ Literal quote characters instead of entities improve readability
- ✅ Updated jQuery libraries (minified versions) improve performance

### For Backwards Compatibility
- ⚠️ New event fields should be treated as additions (not breaking)
- ⚠️ New parameter `preventLockLevelReset` is optional
- ⚠️ Sample JSON default values changed (may affect test/mock
implementations)

---

## Notes for Reviewers

When reviewing this file in GitHub:
1. **Use whitespace filtering**: Enable "Hide whitespace" in the diff
viewer
2. **Focus on**:
   - Event field additions and reordering
   - Sample JSON value changes
   - New access scope information
   - Test link URL updates
3. **Skip reviewing**: HTML entity encoding, self-closing tags, and
formatting changes (they don't affect functionality)

---

Generated: January 27, 2026

Author: iMicknl

docs/api/apiDocStyle.css

@@ -95,6 +95,12 @@ td.pr {
 	text-align: center;
 }
 
+.m_patch .m {
+	color: white;
+	background-color: #88008f;
+	text-align: center;
+}
+
 .m_get    .p {
 	color: black;
 	background-color: #e7f0f7;
@@ -123,6 +129,13 @@ td.pr {
 	border: 1px #efd5d6 solid;
 }
 
+.m_patch .p {
+	color: black;
+	background-color: #f4e8f5;
+	text-align: left;
+	border: 1px #e9d5ef solid;
+}
+
 .m_get    .d {
 	color: black;
 	background-color: #ffffff;
@@ -151,6 +164,13 @@ td.pr {
 	border: 1px #efd5d6 solid;
 }
 
+.m_patch .d {
+	color: black;
+	background-color: #ffffff;
+	text-align: left;
+	border: 1px #eed5ef solid;
+}
+
 .m {
 	border-top-right-radius: 5px;
 	border-bottom-right-radius: 5px;
@@ -160,7 +180,7 @@ td.pr {
 pre.m_desc, pre.c_desc {
 	white-space: pre-wrap;
 	word-wrap:break-word;
-    margin-left: 10px;
+	margin-left: 10px;
 }
 
 th {
@@ -241,6 +261,18 @@ span.list:hover, span.expand:hover, span#listAll:hover, span#expandAll:hover, sp
 	font-style: italic;
 }
 
+.rateLimited {
+	margin-left: 10px;
+	color: orange;
+	font-style: italic;
+}
+
+.scoped {
+	margin-left: 10px;
+	color: #3344FF;
+	font-style: italic;
+}
+
 span.list:hover, span.expand:hover {
 	color: #6e6f70;
 }
@@ -261,6 +293,10 @@ span.list:hover, span.expand:hover {
 	color: #a3201c;
 }
 
+.fs:hover .rel.m_patch {
+	color: #88008f;
+}
+
 .c_det {
 	display: none;
 }