Feature: BloodHound related-entity-query-results response type is polymorphic but does not provide a discriminator to the client

[daviditkin]

Feature Description

BloodHound needs to support a discriminator for the polymorphic response type, related-entity-query-results. related-entity-query-results use of oneOf without providing a discriminator does not allow generated client code to unambiguously un-marshal the response.

Are you intending to implement this feature?

yes

Current Behavior

Generated client code can not un-marshal the related-entity-query-results response into one of the three polymorphic types.

Desired Behavior

Provide a discriminator in the repose that allows generated code to un-marshal the response.

Use Case

Using a generated client to access endpoints that return a response type related-entity-query-results

Implementation Suggestions

Add a discriminator to the related-entity-query-results and modify the server to set the discriminator properly depending on the json result.

Additional Information

[sircodemane]

Hi @daviditkin, after reviewing, we would like to alter to requirements for this. Due to the nature of some of the responses, particularly count and graph, there is not a path for altering the endpoint responses in such a way that does not break the API contract. After reviewing usage and different solution paths, we have decided that we feel the best way to move forward is as follows:

• No changes to the API side or responses
• Change the related entity query response to no longer be represented in the spec as polymorphic and instead show the list response type only.
• Keep the type parameter documented, but add a note that count and graph are unsupported
• Add more details to the related entity query response description to describe that the count and graph responses are undocumented and unsupported and will result in a different response structure than defined in the spec.

This should fix the code generation issue as the endpoint will have a static response structure as documented in the spec (eliminating the oneOf clause), and the true polymorphic nature of the endpoint will only be mentioned but not officially supported or documented in the spec.

If you have any questions or concerns, please feel free to reply here! Thanks

[sircodemane]

Apologies for the adjustment, I'd like to add one more thing to the requirements: in the related entity query response description, it would also be useful to call out the name of the graph response structure for those who are interested in using the unsupported endpoint. The generated schema name is model.bh-graph.graph