Using typeless maps on api boundaries

Question

What do you think about passing typeless maps to APIs (packages, systems, adapters) outer to Core Domain as in 1st Way below?

Strongly-typed objects are inside Domain API, and business rules are using them.

1st WAY:

Domain  ->  Web API  ->  Clients
Passes strongly-typed domain objects

• Whenever a request comes from the Web API, it requests to Domain and Domain passes the strongly-typed domain objects (like: []SomeDomainObject) to the API

• Then, the Web API transforms these into JSONs and response back to the clients

2nd WAY:

Domain  ->  Web API  ->  Clients
Passes property maps which loose their types

• Whenever a request comes from the Web API, it requests to Domain and Domain transforms the strongly-typed domain objects into property maps (like: map[string][object]) and passes them to the API

• Then, the Web API transforms these into JSONs and response back to the clients

---

In the 1st way:

• When domain objects or rules change, that can affect Web API. For example: Web API needs to accommodate itself for the new data added to the domain objects.

• So, change in Domain reflects in change in outer services because of types

In the 2nd way:

• Domain controls everything. Whenever domain objects or rules change, Web API will automatically response back with what the domain wishes.

• Any change in Domain automatically be reflected to outer clients, because they'll not need to see Domain entities, they'll only see properties. And, can easily pass them to the clients as they're supplied from the Domain.

• Downside is that Web API will loose the strong type-safety of Domain objects and will only see typeless property maps.

Answer 1

There are no advantages to the 2nd method and many disadvantages.

you state:

Whenever domain objects or rules change, Web API will automatically response back with what the domain wishes.

But in fact the web api code doesn't change in either case and the web api deployment changes in both.

A strong type can be serialised to JSON via reflection without hand coding. So no code change is required If you add or remove properties for example.

Similarly, If you update the domain in the 2nd method, you still need to deploy that updated code, presumably compiled or bundled with the api code. So there is a change required to the api layer.

Ideally the Api layer should be transparent to the client and domain. For the client, calling the api should be the same as calling the domain directly. strong types and all.

At the end of the day the client code needs to know the structure of the data in order to function. So you need versioned 'types' either through schemas or by publishing strongly typed client libraries.

Answer 2

Either way is viable in their own way. Though if I may make a suggestion on the 2nd way using properties, do yourself a favor now and provide a version as a property. Otherwise you risk creating unnecessary problems client side during upgrades.

I'm partial to the 1st way, but that really only works if the interface is mostly solidified and isn't likely to change. If you're adding or changing new fields and methods all the time, it will create frequent hair-pulling. Mind you, you can still use the 1st way with a little bit of the 2nd way mixed in for good measure. For areas where you expect there to be frequent changes, you can still prefer use of a map to represent key-value pairs. It only requires a little bit of future-proofing on your part ahead of time.

And as always, be sure to follow the convention of minor version changes for backwards compatible API changes and major version changes otherwise as a good general rule of thumb.