[mumblemumble]

The only time I've ever encountered an API that used it extensively, it was done by a company that does all their implementation in Java.

My best guess at what happened, based on the shape of the API, is that they implemented it by taking their pre-existing domain model, which had a fairly deep subclassing hierarchy, liberally sprinkled some annotations from com.fasterxml.jackson.annotation, and dumped the result straight onto the wire.

You could absolutely do an object-oriented codebase where two different subclasses have fields with the same name and different types, and, depending on how you structure your code, it might not be too painful. And it's fairly easy to imagine someone serializing a structure like that to JSON without ever meditating on the fact that JSON won't retain the all the type information.

Ironically, the end result was an API that is nigh-impossible to consume from Java. I ended up writing a façade in Python.

I've also seen little bits of this happen in the internal APIs at my current company. Also a Java shop, also a result of trying to directly connect an internal object model to the API. I've never seen it done in an API implemented in a dynamic or functional language.

[pwinnski]

I hadn't considered the one-way nature of dumping Java classes to JSON.

Mainly because I work with classes that are serialized both to and from JSON, rather than having Jackson annotations added much later.

I can see it now. Horrifying! I'm sorry for your troubles.

[mumblemumble]

My take-away is this: Protocols should always be defined independently of any existing code.

The code-first approach only works well when you're doing something self-contained. Which, an API, almost by definition, is not.

[pwinnski]

I generally try to design APIs from a consumer perspective, and then usually I end up with something RESTful. Let the server do whatever it has to do, you know?