Skip to content

doc: Entity management API documentation#3659

Merged
albinsuresh merged 2 commits intothin-edge:mainfrom
albinsuresh:doc/entity-management
Jun 21, 2025
Merged

doc: Entity management API documentation#3659
albinsuresh merged 2 commits intothin-edge:mainfrom
albinsuresh:doc/entity-management

Conversation

@albinsuresh
Copy link
Copy Markdown
Contributor

@albinsuresh albinsuresh commented Jun 2, 2025 •
edited
Loading

Proposed changes

  • Introduce dedicated documentation for entity registration MQTT APIs
  • Refactor old entity deregistration MQTT API doc

Types of changes

  • Bugfix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Improvement (general improvements like code refactoring that doesn't explicitly fix a bug or add any new functionality)
  • Documentation Update (if none of the other choices apply)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)

Paste Link to the issue


Checklist

  • I have read the CONTRIBUTING doc
  • I have signed the CLA (in all commits with git commit -s. You can activate automatic signing by running just prepare-dev once)
  • I ran just format as mentioned in CODING_GUIDELINES
  • I used just check as mentioned in CODING_GUIDELINES
  • I have added tests that prove my fix is effective or that my feature works
  • I have added necessary documentation (if appropriate)

Further comments

albinsuresh
albinsuresh commented Jun 2, 2025
View reviewed changes
docs/src/operate/registration/index.md Outdated
@@ -1,11 +1,21 @@
---
title: Registration
title: Entity Management
Copy link
Copy Markdown
Contributor Author

@albinsuresh albinsuresh Jun 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open to use any other title like Entity Lifecycle Management that covers CRUD operations on entities. Even the side-pane title (directory name) which is currently Registration could be changed accordingly.

Copy link
Copy Markdown
Contributor

@didier-wenzek didier-wenzek Jun 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Entity Management is okay

Copy link
Copy Markdown
Contributor

@reubenmiller reubenmiller Jun 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably rename the folder then from "registration" to "entity-management"

Copy link
Copy Markdown
Contributor Author

@albinsuresh albinsuresh Jun 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will rename the folder right before the merge.

docs/src/operate/registration/http_api.md
@@ -83,158 +83,79 @@ GET /v1/entities/{topic-id}
curl http://localhost:8000/te/v1/entities/device/child01
```

## Query entities
Copy link
Copy Markdown
Contributor Author

@albinsuresh albinsuresh Jun 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The diff of this file is a bit weird. All I did was to move this Query entities section to the end of this file so that the CRUD operations are placed together. This Query entities section was quite big and in the middle of them earlier, placed along with Fetch entities(as querying is also another kind of READ operation).

@albinsuresh albinsuresh marked this pull request as ready for review June 2, 2025 05:50
@codecov
Copy link
Copy Markdown

codecov bot commented Jun 2, 2025

Codecov Report

All modified and coverable lines are covered by tests ✅

📢 Thoughts on this report? Let us know!

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

didier-wenzek
didier-wenzek reviewed Jun 2, 2025
View reviewed changes
docs/src/operate/registration/index.md Outdated
import DocCardList from '@theme/DocCardList';

Managing registration and deregistration of child devices and services on %%te%%.
%%te%% provides two different API interfaces for managing entities on a device:
Copy link
Copy Markdown
Contributor

@didier-wenzek didier-wenzek Jun 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This introduction is missing something. The focus is on HTTP vs MQTT but the purpose of these APIs is a bit vague. I would give a short overview of these core functionality.

Suggested change
%%te%% provides two different API interfaces for managing entities on a device:
%%te%% provides an API for managing entities on a device: to register child devices and services with metadata describing their role and relationship.
%%te%% provides two different flavor of this API:

Copy link
Copy Markdown
Contributor Author

@albinsuresh albinsuresh Jun 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Revamped this intro significantly in 4ff49e7, highlighting the pros and cons of both APIs

@reubenmiller reubenmiller added documentation Improvements or additions to documentation theme:entity_store Entity store related functionality labels Jun 2, 2025
didier-wenzek
didier-wenzek reviewed Jun 2, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor

@didier-wenzek didier-wenzek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a single world is said about updating an entity over MQTT. It would be good to tell what the restrictions are.

@reubenmiller reubenmiller added theme:entity_store Entity store related functionality and removed theme:entity_store Entity store related functionality labels Jun 10, 2025
reubenmiller
reubenmiller reviewed Jun 10, 2025
View reviewed changes
reubenmiller
reubenmiller reviewed Jun 10, 2025
View reviewed changes
reubenmiller
reubenmiller reviewed Jun 10, 2025
View reviewed changes
reubenmiller
reubenmiller reviewed Jun 10, 2025
View reviewed changes
reubenmiller
reubenmiller reviewed Jun 10, 2025
View reviewed changes
reubenmiller
reubenmiller reviewed Jun 10, 2025
View reviewed changes
docs/src/operate/registration/http_api.md

To demonstrate different query examples, the following entity tree is assumed as the base:

```
Copy link
Copy Markdown
Contributor

@reubenmiller reubenmiller Jun 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be more clear to users if we simplify the example a bit, e.g. only going 2 child devices deep, and using 1-2 services per device...not sure if we could also use some more realistic names, e.g. tedge-mapper-c8y, and tedge-agent on the main device?

Copy link
Copy Markdown
Contributor Author

@albinsuresh albinsuresh Jun 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolved by 30a930c

didier-wenzek
didier-wenzek reviewed Jun 16, 2025
View reviewed changes
didier-wenzek
didier-wenzek approved these changes Jun 16, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor

@didier-wenzek didier-wenzek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved

@albinsuresh albinsuresh requested a review from a team as a code owner June 20, 2025 10:51
reubenmiller
reubenmiller approved these changes Jun 20, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor

@reubenmiller reubenmiller left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved

@albinsuresh albinsuresh force-pushed the doc/entity-management branch from 9a6322b to aebd479 Compare June 20, 2025 12:08
@albinsuresh albinsuresh temporarily deployed to Test Pull Request June 20, 2025 12:08 — with GitHub Actions Inactive
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Jun 21, 2025

Robot Results

✅ Passed ❌ Failed ⏭️ Skipped Total Pass % ⏱️ Duration
651 0 3 651 100 1h46m43.591501s

@albinsuresh albinsuresh added this pull request to the merge queue Jun 21, 2025
Merged via the queue into thin-edge:main with commit c440c03 Jun 21, 2025
34 checks passed
@rina23q rina23q mentioned this pull request Jun 23, 2025
Merged
11 tasks
@albinsuresh albinsuresh deleted the doc/entity-management branch July 21, 2025 06:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@reubenmiller reubenmiller reubenmiller approved these changes

@didier-wenzek didier-wenzek didier-wenzek approved these changes

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation theme:entity_store Entity store related functionality

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@albinsuresh @reubenmiller @didier-wenzek