If a field is added in a JSON response, is this considered an API change? Yes 👍 / No 👎 ?

yes. It’s a backwards compatible API change.

Yes, this would typically constitute a breaking change to the API. Even if the value of

"car"

is

null

, if a consumer has as class which does not have a

car

property and

ignoreUnknownKeys

is

false

, the new JSON response would throw an error

Yeah I was also wondering how

ignoreUnkownKeys

would play into this. I think for most other deserializing clients (eg. the general question) this would be backwards compatible.

it depends on the expectations between the endpoints involved, but this is typically considered to be a compatible change.

If ignoreUnkownKeys default is false, which will crash the deserialiser with such a change, then how is that typically considered to be a compatible change?

kotlinx serialization is the first deserialization client I’ve ever used that has this “strict” mode enabled by default.

It might not be the “standard” to be so strict, but consider that, unlike most serialization libraries, this one is designed so that you use the same serialization models on both the server and client. Most other languages that can do that are either dynamic and don’t really need specialized serialization libraries (JS), or else use different languages/libraries between client and server and can’t make any assumptions about the structure of JSON given a class. That said, I’ve found this library to bit a bit difficult to use for parsing arbitrary JSON structures. It definitely works the best when you use kotlinx.serialization on both the client and the server. I do usually keep

ignoreUnkownKeys: true

and

isLenient: true

whenever I’m not using the same models on the server, because 3rd party servers are the wild west and always end up sending stuff in production that I didn’t expect.

It might not be the “standard” to be so strict, but consider that, unlike most serialization libraries, this one is designed so that you use the same serialization models on both the server and client.

This doesn’t matter when you’re deploying applications to an app store where you have no control over when your clients are actually updated unfortunately.

Interesting take Casey, ty. I'm thinking Android too here

That’s a fair point. I can’t tell you how many times my clients have said “can’t you just force update when there’s a change to the API?” No. The answer is always no. A non-compatible change to the API will certainly break Android and iOS apps.

Yup.

the kotlinx.serialization.json default of

ignoreUnknownKeys=false

confuse me, especially since kotlinx.serialization.protobuf has its behavior default to the equivalent of

true

(as is the expectation for that format)

I generally think it’s a bad default, too.

Even you intend to share models between server/client, you typically can't guarantee simultaneous deployments of client and server..

thats true too

The above is very similar to best practice with database migrations. You generally want application code and a migration to be backwards compatible for deploy 1 and then can remove the cruft in deploy 2 after deploy 1 succeeds (assuming a client/server model for an RDBMS).

So moral of the story when making non-compatible changes to your API: 1) update your client apps with the

car

property in its model 2) Deploy to the app stores 3) Wait 2 weeks for 80% of your apps to be updated 4) Deploy the not-backward-compatible server changes to production 5) 20% of your users start complaining about crashes 6) customer service tells everyone to just update their apps 7) folks still don’t update their apps

step 0: Set

ignoreUnknownKeys

to true and communicate expectations to your backend devs

Or, just make sure

ignoreUnknownKeys

is true the next time you release, and hopefully don’t have to worry about this as much

7 is my favorite

moral of the story is that you need to set up the apps to allow for future changes, or your changes always go to new endpoints that the older clients aren't using

Reading this doc, it reads like: We recognise that "...new properties can be added during the API evolution", but we're gonna crash by default anyways

I think GraphQL does a lot of things poorly, but one thing that’s super nice about it is having a type schema that allows for API evolution and deprecations.

I think with GraphQL the clients can select (query) which things from the database they want to consume as JSON. Its just another form of change management, in effect similar to versioning

There’s more to it than that. You can build rich APIs on top of GraphQL. I use it every day.

there are a couple of pain points with GraphQL - we've run into https://github.com/graphql/graphql-js/issues/1361 more times than I can count, and https://github.com/graphql/graphql-spec/issues/550 makes it harder to deprecate and migrate. but overall it's a reasonably good story

Let me be clear — I hate GraphQL. I just think that having a codified schema with types and deprecations is nice.

ditto JSON, without extensions that don't work on every platform

A haven’t used GraphQL in a while, but I also found I didn’t care for it much. Its goal of being language-agnostic actually made it pretty difficult to match its schema semantics into any language except JS (since it’s dynamic). Such is the world we live in. JS is the only supported language for most things, apparently.

Yup. JS and its dumb 53 (I think?) bit numbers integers

IEEE-754 binary64 gives you precise integers up to 2^53, yes

Which is great for money

for the record, it's not just a JS issue. Lua does the same thing

Any language which smooshes the semantics of integer types and floating point types into one thing

You probably shouldn’t be using floating-point numbers for money at all. A 2-integer system is safer and doesn’t lose precision (which is basically what Java’s

BigInteger

does under the hood)

Js just happens to be the one we’re all forced to use

at one of my previous companies, all currency was represented in millis as int64

The GRPC money class is overkill but it’s nice they provide it out of the box

I would make an integer joke, but they just don’t have any point

or alternatively, sometimes “stringly-typed” values are actually the better way to go. Don’t trust the framework to handle numbers correctly, do it all yourself. Painful, but safe

If you can agree on what format to represent your stuff in, maybe. I work for a global org where locale is at the centerpoint of all money representations so I would balk at that idea as dangerous.

yeah. our current product has integer IDs on the backend but the clients don't need to know that. as far as the clients are concerned, all IDs are simply opaque strings.

protobuf money for reference. https://github.com/googleapis/googleapis/blob/master/google/type/money.proto

oh nanos is incredibly overkill lol

centerpoint of all money representations

For example, we recently had a prod bug regarding eastern arabic numerals. There’s also some weird stuff with bulgarian where they culturally don’t include a

,

as a grouping separator but only when dealing with money. If it’s normal numbers they do. So strange.

^ yup, I’ve seen that kind of issue before. In my case, it was a phone set to Turkish locale inserting a

,

instead of

.

for the decimal portion of the USD

(if that's your issue, you have problems with far more locales than just Turkish)

Fortunately, my client only has US-based customers dealing in USD, so we could just hardcode the US locale. But don’t get me started on how terrible the API was that we had to deal with money representations like that at all…

Here’s the TL;dr on money formatting. 1. The formatting of the number and the currency symbol relates to the locale a user is trying to view that information in. Eg. Their device locale. 2. The type of currency a customer/user is interacting with has to deal with what country/merchant/entity they’re interacting with.

hard-coding currency per region is also not great: see above where HRK disappeared, or the VEF/VES change a few years ago (not that VES is stable either)

Yup. Currency should generally be delegated from a server

The reason for the default value of

ignoreUnknownKeys

is simple API compatibility. This key was introduced later (per user demand), but allowing the default behavior to change would break the expectations of many existing users. As such it is stuck to

false

until there is some reason to have an API incompatible change.

wasn't

Json.ignoreUnknownKeys

pre-1.0? there already was a bunch of API-incompatible changes for 1.0