3 ms·

I very much agree with your first and third point, from experience. As for the second one — if consuming dynamic data structures is hard in typed languages, may

I very much agree with your first and third point, from experience. As for the second one — if consuming dynamic data structures is hard in typed languages, maybe they are not the right tool for that particular job? What I have seen is endpoints trying to corral their responses into one-size-fits-all schemas in the situation you're describing, with predictable outcomes. Lots of overhead in most situations, tricky documentation, lots of optionals. Under that premise, I have to say that at least for generic APIs with many differing clients, the idiosyncrasies of typed-language clients would not rank too highly on my list of design considerations — not when they are in the way of simpler, easier to understand responses.

Joker_vD 3y ago
As for the second point, that's what Accept header is for. And I personally never had much trouble in Go with deserializing all those "weird response types" but it may depend on one's coding style. > I have to say that at least for generic APIs with many differing clients, the idiosyncrasies of typed-language clients would not rank too highly on my list of design considerations Hey, would you like to consume an exchange format that has meaningful distinction between strings and atoms? Those come from the dynamically-typed languages area!
physicsguy 3y ago
So, for 2, what I mean is stuff like: GET /api/object/<id>?withAdditionalMetadata=1&expandChildren=1&..... So then the OpenAPI schema has to be something like: schema: oneOf: - $ref: '#/components/schemas/Object' - $ref: '#/components/schemas/ObjectWithMetadata' - $ref: '#/components/schemas/ObjectWithChildren' - $ref: '#/components/schemas/ObjectWithChildrenAndMetadata So inevitably the client ends up being quite complex to handle this.