-
Notifications
You must be signed in to change notification settings - Fork 671
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Feature: Enhance OpenAPI Specification by Structuring Endpoints Based on Entities for Improved Clarity and User Experience #2053
Comments
@arvindh123 Also, consider this option:absmach/magistrala-old#261 (comment) |
@dborovcanin , I agree with your idea absmach/magistrala-old#261 (comment) |
@arvindh123 What's the plan with this one, should @Musilah start working on it, but with absmach/magistrala-old#261 (comment) 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? |
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). |
An Example case :
|
@felixgateru Please rebase the upstream feature branch and send a PR for this. |
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 thethings
associated with a user, even if thethings
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 expectusers.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
The text was updated successfully, but these errors were encountered: