Should I share types between a Web API service and its client ? What are the other options?

Question

We are developing a Web API RESTful service to provide access to common data to all the applications of our enterprise. To help we will also publish a Client API that encapsulate all the HttpClient details and provides a strongly-typed access to the data.

Our goal is to start small and progressively add features, while still keeping backwards compatibility with already deployed versions of the client API (compatibility with the clients of the same Major version)

While talking about the design, our team just had a very long discussion about whether or not we should share types between the server and the client (for instance via versionned NuGet packages that both server and client would depend on), and ended up with pros and cons ... and we do not manage to decide one way or another.

Sharing types (shared assembly) between client and server

Pros

• Client model and Server model are always up to date
• no serializing/deserializing problems because same types are serialized/deserialized
• no duplication

Cons

• need to find a way to share the types between server and client
• non semantic modifications can break existing client applications (changing the name of a class or its namespace in the server model) even though it has no impact on the serialized json and should therefore have no impact
• risk of breaking the clint without realizing

Separate (but structurally equivalent) types for client and server

Pros

• client "model" is less coupled to the server implementation (just a mirror of the Json output by the server, but no hard "same type" relationship)
• server model can evolve without risk of breaking any client
• enable to enhance the client-side model independently from the server model
• the client model is part of the client package, no "shared package" to maintain between server and client

Cons

• duplication between server code and client code
• error-prone task of keeping server-side and client-side structure in sync

There seems to be a 50/50 preference for each solution in our team.

I personally have a preference for the second option, because I believe RESt is all about decoupling, and decoupling means the client should not care about how the server side is implemented (which types, or whether it is a .NET app anyway) but wish we could get rid of the possible duplication, maybe thanks to code generation or something like that, but could not find any guidance on the subject

Are there other pros and cons to sharing types between client and server ?

If we do not share them, are there ways to lower the maintenance costs when trying to keep client model and server model in sync ?

Answer 1

I would argue that if you are not careful, the second option could end up being less RESTful than the first. REST is less about de-coupling and more about managing and focusing the coupling between client and server.

In a restful system you know the coupling between client and server lies in the media type definitions and the link relation definitions.

In both options, you are effectively sharing types between the client and the server. In the first option this sharing is explicit via a concrete implementation that could be managed as a nuget package and versioned independently of client and server.

In the second option you have two implementations of the shared types. However, I'm guessing you are not planning on defining a media type that explicitly defines what the properties of those types are. Therefore you have no single source of truth, you have nothing to define what the data contract between client and server is. How do you know when you are going to make a change that will break a client? At least with a shared library you can know that the server is now using version 1.4.7 of the shared types and the client is using 1.3.9. You can use semantic versioning on the shared type library to know when you are making a breaking change that will force the client to update.

With the second option, you have a client and a secer that will be independently versioned and it will be much harder to keep track of whether there are breaking changes between the two versions.

Explict Media types are always the best way to capture the contracts and version the contracts between HTTP clients and servers. However, if you don't want to go there, then the shared nuget library is the best next step because you are isolating the part of the system that is shared from the client and server implementations. This is one of the key objectives of REST. The fact that you are actually sharing an implementation library of that shared contract only affects consumers live on other platforms that can't consume that library.

I coined the term Web Pack a few years ago to describe this idea of using a shared nuget package to contain the shared coupling. I wrote a few articles here and here on the subject.