-
Notifications
You must be signed in to change notification settings - Fork 47
Openapi: we need an Array and fields contract. #568
-
The REST Endpoints are growing and we need a formal contract between server and client. Without it the client never knows what to expect from the backend.
Arrays
It has been mentioned in some discussions that fields whose type is an array should never been NULL but rather an empty array or an array with values.
What is our position on this? I personally suggest having an empty array rather than NULL
Fields
Let's use the Openapi definition to know which fields are mandatory and which ones are optional (nullable). When using Swagger the mandatory fields always have a red cross next to the field name.
I suggest appropriately using this as it would simplistic to mask every field as optional and avoid having a proper design.
Beta Was this translation helpful? Give feedback.
All reactions
Replies: 4 comments 3 replies
-
We can certainly emit empty arrays when there's no data, instead of skipping the field.
Beta Was this translation helpful? Give feedback.
All reactions
-
I don't think we ever have null. We might skip the field, or have an empty array.
Beta Was this translation helpful? Give feedback.
All reactions
-
👍 1
-
Just to be clear.
Skipped:
{}Null:
{
"items": null,
}Empty:
{
"items": [],
}Beta Was this translation helpful? Give feedback.
All reactions
-
True, but Javascript, being a little special, makes obj.items undefined in both of the first two cases, afaik.
Beta Was this translation helpful? Give feedback.
All reactions
-
null and undefined are slightly different in JS and the difference is testable.
Beta Was this translation helpful? Give feedback.
All reactions
-
Perhaps I shouldn't have used the word "null" as it is a particular thing of a language. Sorry for that. My main point is:
- For fields whose type is an array then always return a value. An empty array or an array with values
- I wonder is there is a global way of configuring Serde or whatever tool the backend is using to avoid this things even being discussed. Configuring these things field by field is error prone. I can see lines of code like:
- For fields whose type is string|number then we should document them appropriately in the openapi spec as it represents the contract between clients-server
My original intention is to avoid issues like the one reported here guacsec/trustify-ui#114 .
Beta Was this translation helpful? Give feedback.
All reactions
-
That's a tricky thing, and I actually tried coming up with Rust RFC, trying to capture exactly that problem. Which resulted in an PoC crate: https://github.com/ctron/isx
Right now, there is no global definition of "empty" in the Rust ecosystem. Therefore serde allows providing that with a custom attribute. For some types "empty" is simple (Option, Vec, *Map). For others, it isn't (String, integers, boolean). In such cases, people tend to go for "is default". Which hover is specific to the type. And might be specific to the language's ecosystem.
So I think your proposal of coming up with a set of rules for our project makes perfect sense. My proposal would be to omit everything that could be "empty", from the perspective of a "contains no elements" perspective. That should work well for Option and any kind of list, map. I might hope this should also work well in the TypeScript ecosystem.
All other values (strings, booleans, integers, ...) should either be wrapped into Option explicitly, or never be skipped.
Beta Was this translation helpful? Give feedback.