Loosen coupling over APIs – The Fuzzy Serializer

Currently I am working at a SaaS company, whose client base is in the large enterprise space. We are currently increasing our API surface area, to enable greater integrations.

As we iterated on the API (by simply adding more properties), we discovered that one of our clients had tightly coupled to our API, which caused their integration to break when we released the change.

A quick discussion with the client revealed we had varying definitions of “breaking change vs non-breaking change”, and expectations about coupling / resiliency.

For example;
Does adding a new property to the response payload equate to a breaking change?

Regardless of the answer, it made me realise;

  1. We had not defined what we see as a breaking change, we assumed our clients share our view
  2. We cannot directly control the amount of resiliency or coupling they build into the integration with our API.

Following Postel’s law:

Be liberal in what you accept, and conservative in what you send.

We defined breaking change as:

  1. Change in behaviour / validation
  2. Rename / removing properties or fields
  3. Change in VERBS, Response codes, Error messages etc.

Non breaking change as:

  1. Reordering / Additional properties
  2. Additional endpoints

Reality is, not every developer reads the documentation. Is there anything else we can do to help our clients?

How can we ensure the consumer of the API will not break if we add a new property?
How can we ensure, the consumer of the API is not relying on the order of the properties in the response?

Introducing PageUp.FuzzySerializer. The PageUp Fuzzy Serializer is an extension to Newtonsoft Json.Net which tries to enforce the two questions above while serialising the response to the consumer.

1. It will add a new random property to the response everytime it is serialised over the wire.

2. It will shuffle the response to the consumer, so the consumer does not rely on the order of the response.

Assuming the client calls your API at least twice, this ensures the consumer is respecting Postals law.

Original Response:


  "Name": "Abhaya Chauhan",
  "Country": "Australia",
  "Gender": "Male"


“Fuzzied” Response:

  "Gender": "Male",
  "Name": "Abhaya Chauhan",
  "83da62fa-b4e1-4d2d-98f8-a926b90e9158": "338d123c-62dc-48e4-b7c0-f5f3fcc1aa9b",
  "Country": "Australia"

As you can see, we’ve added a new property, and shuffled the order of the response.

Check out the Nuget packages / Github repo for more information:

  1. Github
  2. Nuget: PageUp.FuzzySerializer
  3. Nuget: PageUp.FuzzySerializer.Net
  4. Nuget: PageUp.FuzzySerializer.Legacy

Leave a Reply

Your email address will not be published. Required fields are marked *