thentos
thentos copied to clipboard
liqd
Only use JSON objects
Insofar as possible, for both requests and responses. (Rather than top-level strings, arrays, etc.)
It'd be nice to put some thought into the design of the API, since once a system is live changing it is a bad idea. What should e.g. an object that returns a session token look like (in -core, not -a3)? Should the JSON responses themselves be versioned?
yes, versioning is cool! it can also be added in the second version ever, and a missing version identifier means "first version ever", but if we build it in now we avoid overlooking something.
where would you put the version identifier? header? path? json body?
Actually, thinking about it a bit more, I think I'm against versioning data. It will lead us into the mistake of thinking we can change the API partially and not update the entire version. (We can of course version the entire API, but that's not really related to this question.)
For sum types, should the standard be that there's a type field disambiguating between constructor cases?
Does it make sense to use generic From/ToJSON? I like them well enough when the discipline we follow is that changes to interface types are changes to the interface, and should basically never be made, but if there's no such notion, having explicit instances makes it easier to change the types without changing the interface. Also, I think in a lot of places we ended up using quite bad names for fields just because it's convenient to not have matching record names in Haskell-land.
@jkarni: also, "yes" to the type field. About versioning: Not sure I follow, but if you want to postpone versioning I'm ok with that.
How hard would it be to start using JsonGrammar or something similar?
I'm also against versioning (for the time being at least). type field sounds reasonable.
Moved some of this to https://github.com/liqd/thentos/issues/330 since it's more appropriate (and there's the threat of mission creep here).
I've recently introduced the JsonTop type (defined in Thentos.Types) that allows wrapping a simple value (jsonified as string, number, bool, or even array) into a JSON object ({"data": <simple value>}). We should use that one everywhere in the API where we would otherwise return a non-object value.
I've already revamped the "user" part of the Simple core API to use it, but the rest of the core API may still need to be adapted.