Replies: 1 comment
-
I certainly have thoughts on this, I have to deal with it all the time in my full time job~ 😅
#385 for even more context on this design decision for anyone who's interested 😊
Yup, and adding new params that are not required is generally best practice to maintain backwards compatibility.
Okay now to the meat of it—the short answer is if your fields are fixed in your response, you should include them in Reason 1: your response fields are not fixedBefore I found FastAPI, I used Flask-RESTPlus which contained a neat feature where it would read a header to determine which fields to respond with. This let you do some GraphQL-like-stuff by reducing over-fetching. It's not very idiomatic to OpenAPI, but it is possible! You also might want to do something like tagged unions but your tooling (looking at you Pydantic + FastAPI) doesn't support it. An easy workaround is to have some fields be not required. You could also use null with a default for this but then you are transporting a bunch of nulls. You could also have some response semantics that involve reducing network I/O by omitting some fields some times when they aren't needed. Again, this probably indicates some other problem with design, but it's an acceptable usecase in the spec. Reason 2: you want your generated clients to be backwards compatibleWe considered this solution as part of a problem we have in our development cycles. It goes something like this:
|
Beta Was this translation helpful? Give feedback.
-
Context: Today, unless a field is marked as
required
, it will result in a model property that is of typeUnion[<type>, UNSET]
in generated models.This works great for writes - we generate objects that serialize only the expected fields, and it's very common in openapi specs to include which parameters are required for writes.
OTOH, for reads (aka responses from the server):
required
As I understand the state of
openapi-python-client
we generate objects from responses where additional code is often needed to check if the values areUNSET
, or assertions are needed to stop mypy from complaining.So, what I'm confused about is - it seems like either tons of people are writing their openapi specs wrong (and not marking all response fields as
required
), or the client should behave differently when serializing/deserializing reads vs. writes.What do you think? Should
required
&UNSET
behavior be asymmetric for reads and writes? Should OpenAPI specs always mark fieldsrequired
in response objects if they're always going to be returned?This has been the topic of some discussion at Benchling - I want our OpenAPI spec to be as correct as possible and It's not clear to me if marking response fields as all required is "appeasing the SDK" or "writing a good spec" 😄 .
I'd love to know your thoughts!
Beta Was this translation helpful? Give feedback.
All reactions