GraphOS Platform API Feedback - Visualizing fields

[Bostwickenator]

Context

When using Apollo Studio as a documentation tool there is no good way to link to a specific field. While it is possible to generate a link which does point to a specific field it is returned inside a list of search results in a four column view Fields|Details|Subgraph|Actions. This means that the documentation (i.e. Details) for query fields are compressed into a thin column and readability is poor. It also causes information overload as it is more difficult than necessary to grok which parts of the list you are viewing are relevant to the link.

Examples:

• https://studio.apollographql.com/graph/example/variant/qa/schema/reference/inputs/FavoriteColorsInput - A single page view showing things logically scoped to a small region of the graph.
• https://studio.apollographql.com/graph/example/variant/qa/schema/reference/objects/Query#FavoriteColors - An anchor in a list of possibly thousands of fields which span all the operations in the graph sorted to put similarly named but logically distinct fields in close proximity e.g. FavoriteSoup, FlavorColors.

This is particularly difficult with fields of the query object which often contain significant important details and appear amidst a lot of visual noise.

I would suggest introducing a single page view for Fields. This would do two things:

• Enable documentation/details to be displayed full width
• Avoid information overload in search results pages

A lower cost work around would be to add a visual callout to the row being linked in a field list such that it is unambiguously the target of the link. Currently this behavior is implemented so that the target of a link highlights only the title of the field and scrolls to the top of the title which cuts off the top of the row.

What type of feedback is this?

• [ ] Question
• [x] Idea
• [ ] Bug
• [ ] New example or operation collection

[timbotnik]

👋 I wonder if you could say a bit more about the audience for this information. For example, we have a Field insights page that has a lot of the things you are asking for (field description, subgraph relationships, field SDL definition) but this page also has a heavy focus on usage metrics / insights (request rates, clients requesting this field, etc.). For this reason it is only available to users with role of Observer+ and not as easily shared with a user who has a Consumer role (e.g. client developer that doesn't have access to usage metrics / insights). BTW you can reach the Field insights page via the schema browser if you click on the "Field Insights" button , or alternatively via the top-level Insights page and searching for a field there.

[Bostwickenator]

Hey @timbotnik yes. I think your intuition is right on the money here. I want to be able to share this information separately from the field insights. This is because one as you note insights can be privileged information and two they can be a distraction from the other pieces of documentation.