Improving Query and Mutation field names #179
Description
Determining good names in OpenAPI-to-GraphQL is a perpetual problem because OAS is not designed to provide the information we need. Therefore, the best we can do is to assume the API well-designed and the OAS is written in an ideal/idiomatic way and provide numerous mechanisms to produce names if any of them fail.
It is impossible to create a solution that will create good names for all APIs and all OASs. That is why we have the operationIdFieldNames option, which allows the user to easily define custom field names manually. This issue is focused on what the default behavior should be given the best conditions.
The current methodology is as follows. Query fields, generally speaking, borrow their names from their respective object types. For example, the field Query.user may return a User object.
We think this strategy allows us to separate from similar projects. We are more data-centric while alternative solutions are more operation-centric. We believe that being data-centric allows us to align more closely with the intent of GraphQL. We are able to reuse object types and create complex nested object type structures.
However, a problem occurs when multiple operations return the same field. Because field names must be unique, only one operation will adopt the name of the data type. The others will default to their operationId. As a result, the GraphQL interface will be non-deterministic and inconsistent.
For example, let's say there are two operations GET /coffeeShopLocation and GET /sandwichShopLocation that return the same kind of location-related data type. The schema of the data type is stored in the components field so it is referenced by both operations and OpenAPI-to-GraphQL knows to reuse the generated data type. In an ideal situation, we will produce a coffeeShopLocation and sandwichShopLocation fields, which both return a Location object type.
Currently, this does not happen. Instead, one field will be named Location and the other field will be named after the operationId. Which operation will take on the location field name is not obvious.
A possible solution is to produce field names form the operation path. This will allows us to create consistent naming for all Query fields. Mutation can follow a similar treatment but also append the operation method in the field name.
However, if this makes assumptions that the URL can easy transformed into a sensible field name. The URL may contain a lot of meta-data concerning the version of the API or other redundant information and it will all appear in the GraphQL interface. In addition, the URL may be too short and nay not convey enough information about the purpose of the operation.
Which solution we should support is difficult to say.