Feature: Enhance OpenAPI Specification by Structuring Endpoints Based on Entities for Improved Clarity and User Experience

[arvindh123]

Is your feature request related to a problem? Please describe.

Structuring endpoints based on entities rather than service-specific endpoints, the proposal seeks to streamline the understanding of functionalities related to specific entities, such as users, things, groups, channels, domains making it easier for users to navigate and comprehend the available API functionalities within a specific context.

Describe the feature you are requesting, as well as the possible use case(s) for it.

Structuring API endpoints not based on service-specific endpoints but rather on entities, For example, within the users.yml file, all endpoints would start with /users. Operations related to specific users, such as retrieving user tags (users/{userID}/tag), would be included here. However, I propose including additional endpoints, like /users/{userID}/things, which pertain to the things associated with a user, even if the things functionality resides in a different service.

By including such endpoints in the users.yml API specification, users interacting with this document will find it easier to understand as they would expect users.yml to provide comprehensive user-related functionalities, even if certain functionalities are fulfilled by other services.

Indicate the importance of this feature to you.

Must-have

Anything else?

No response

[dborovcanin]

@arvindh123 Also, consider this option:https://github.com/absmach/magistrala-old/pull/261#discussion_r1447229367

[arvindh123]

@dborovcanin , I agree with your idea https://github.com/absmach/magistrala-old/pull/261#discussion_r1447229367 I will check the possibilities in code and create a new issue

[dborovcanin]

@arvindh123 What's the plan with this one, should @Musilah start working on it, but with https://github.com/absmach/magistrala-old/pull/261#discussion_r1447229367 in mind? I.e. we keep all the API grouped based on entity, but we also update API accordingly so we do not have confusing endpoints?

[arvindh123]

I think @Musilah can start work on API docs. May be after release we can update API endpoint as per your idea in this comments.

[dborovcanin]

We should also consider just changing the endpoint names. I find grouping "per service" still relevant in case someone wants to integrate with Magistrala API (so knowing which service provides the API may be relevant).

[arvindh123]

An Example case :

/groups/{groupID}/users/-> This is present in Users Service , but start with group This need to changed to /users/groups/{groupID}

[dborovcanin]

@felixgateru Please rebase the upstream feature branch and send a PR for this.

[dborovcanin]

This is blocked by the #2409.