Commenting on Metadata
Introduction
Hasura DDN provides a commenting feature that allows your API producers and consumers to start conversations directly on the API metadata. This feature enhances collaboration by closing the feedback loop and helps teams communicate more effectively about their API design and implementation.
This feature is available for all users on Base and Advanced plans.
How to comment
You can add comments on various objects from your metadata.
- Navigate to any model page in your project via the
Explorertab. - Hover over the field or section you want to comment on.
- Click on the comment icon that appears.
Commenting areas
Explorer Tab
The Explorer Tab is the primary interface where users interact with the API metadata, making it a crucial place for collaboration. Comments here enable API producers and consumers to discuss design decisions, clarify data models, and suggest improvements directly on specific metadata elements.
- Supergraph Page – Comment on the overall schema design, structure, and implementation details of the supergraph.
- Subgraph Page – Provide feedback on individual subgraphs, ensuring alignment with the larger supergraph design.
- Models → General
- Description – Clarify the model’s purpose and usage for better documentation.
- Signature – Discuss function signatures, return types, and argument structures.
- GraphQL Root Fields – Suggest improvements or changes to the root field definitions.
- Models → Fields & Relationships
- Output Fields – Ask questions or provide insights on field usage and expected data.
- Arguments – Discuss argument types, required vs. optional parameters, and potential defaults.
- Relationships – Ensure relationships between models are well-defined and documented.
- Models → Permissions
- Role – Comment on role-based access control settings.
- Read / Create / Update / Delete – Discuss permission settings for different CRUD operations.
This feature is especially useful for teams working on large-scale API projects, as it ensures everyone stays aligned on API structure and permissions.
GraphiQL Tab
The GraphiQL Tab is where users can interactively query the API and test GraphQL operations. Commenting here allows for real-time feedback on API responses, query structures, and potential performance optimizations.
- Discuss unexpected query results and suggest potential schema modifications.
- Collaborate on best practices for query structuring and field selection.
- Provide feedback on performance concerns, such as response times and pagination strategies.
- Leave notes on commonly used queries to improve team-wide API consistency.
By adding comments directly in GraphiQL, teams can streamline debugging and optimize API queries collaboratively.
Insights Tab
The Insights Tab provides performance metrics, traces, and reports about API usage. Commenting here helps teams analyze and discuss API behavior, identify bottlenecks, and track improvements over time.
- Performance – Leave feedback on latency, throughput, and error rates.
- Platform Report – Discuss API usage patterns and suggest improvements.
- Traces – Analyze request traces and collaborate on optimizing execution paths.
This feature is valuable for DevOps, backend engineers, and API consumers looking to enhance API efficiency.
Builds Tab
The Builds Tab allows teams to track and validate schema changes across supergraph, subgraph, and connector builds. Commenting in this area helps teams coordinate schema evolution and avoid breaking changes.
- Supergraph Builds – Discuss schema changes at the supergraph level and their impact on consumers.
- Subgraph Builds – Leave comments about specific subgraph updates and dependencies.
- Connector Builds – Provide feedback on connector integrations and compatibility.
- Schema Diff – Highlight breaking changes or inconsistencies between schema versions.
By facilitating discussions on builds, teams can ensure smooth API evolution and prevent unexpected failures.
Notifications
In-app notifications show new comments made on your project.
The notification hub can be found in the top right corner of the console. On clicking the comments button, you will see all the comments where you are tagged in one place. You can click on a particular comment (deep linking) and go to the original thread on the console. You can also delete notifications from that menu.
You can learn how to invite collaborators here.
Limitations
The feature is in early access and has known limitations, which are in our backlog. Let us know if you would like to prioritize any specific functionality.
- Tagging users on comments
- Resolving comments
- Email notifications
- Ability to auto notify subgraph admin and developers.
- History Tab for comments.
