Comment by Joker_vD
1 day ago
The API consumer is then forced into a slow and frustrating feedback loop:
1. Send request
2. Receive a single error back
3. Fix the error
4. Back to 1., until there are no more errors to be fixed
That's a poor developer experience. We should do better!
Like, "write an actually useful documentation so the developer doesn't have to experiment with remote API, like a blind man groping the elephant"?.. oh. Right, that's a human/organization problem; therefore unsolvable.
Not everybody has this luxury. I once worked on a project where the BE dev had a fundamental issue understanding types (or his PHP code did, who knows), such that, for example, a json array would change its type when empty, e.g.
and many other such issues.
No kidding. I work with an API at my job that does the following:
1. Instead of omitting optional values or at least setting them to null, optional values are set to an empty string when not present (This is including string fields where an empty string would be valid).
2. Lists are represented in such a way that an empty string means an empty list, a list with one element is simply the element, and only lists with more than one element actually use JSON arrays. For example, to represent a list of points ({ x: number, y: number }):
3. Everything is stored in a string. The number 5? “5”. A Boolean? “true” or “false”.
What’s funny is I was able to use serde to create wrapper types for each of these so these atrocities were abstracted away. For example, those arrays I described are simply Vec<T> in the actual types with an annotation using #[serde_as(as = “CursedArray<T>”)][0]. Likewise something similar for the string encoded types as well.
[0]: https://docs.rs/serde_with/3.12.0/serde_with/guide/serde_as/...
Man, I feel you. I did the same, the issue is that I had to regularly update my wrapper types as new exceptions occurred
IIRC, that's because arrays and objects (Associative Arrays) are the same thing in PHP so an empty array can serialized differently than a filled array because it doesn't know if it's associative or not.
Adding this to my PHP Horrors museum.
You can have the best documentation in the world, but if it’s documenting a complex json object with many different combinations of fields, and the user has made a couple of typos, that doesn’t help.
An API which provides more complete failure feedback is a good thing. No need for snark.
This is a bit of a silly take. Even with fantastic API documentation, I've sometimes -- ok, more than sometimes -- made mistakes when crafting my API requests.
Hand craft the json in bash and then call the API from bash.
We do whats we have to to make the lights blink.