1

I'm attempting to find some authoritative references to address this particular scenario. References to best practices guides would be helpful, specifications even more so.

The scenario in question:

A JSON API endpoint that, among other parameters, accepts a list of URLs. An example request JSON might look like:

{
    "foo" : "bar",
    "resources" : ["https://example.com/resource1", "https://example.com/resource2"]
}

So far, so good.

For this call, it is expected that behavior changes based on the presence of those resources. They have semantic meaning. What I did not expect was that the following two calls would be processed differently:

{
    "foo" : "bar",
    "resources" : []
}
{
    "foo" : "bar"
}

The explicit empty list of resources caused the request to be processed as though resources were present. The mere presence of the parameter had semantic meaning, which altered behavior downstream.

Is this considered acceptable practice? References to best practices guides would be very helpful.

2
  • 1
    I would expect an error to be thrown if the parameter wasn't present
    – Ewan
    Jan 28, 2021 at 21:27
  • Is this considered an acceptable practice? only if it's useful for you. And of course, they have different meanings since both are different JSON. Since your serializer doesn't know about your "semantics" you have to set it up to make it compatible with these, The serializer I use most doesn't serialize null fields. Null fields are omitted causing issues if the consumer implements strongly typed mappers. I have to set it up to enforce null serialization (or empty arrays/maps). Or ask the consumers to be flexible and handle the absence of a given field and treat it as null, empty list or map
    – Laiv
    Feb 4, 2021 at 11:30

1 Answer 1

1

Its hard to say without seeing the actual usecase, but a brief google turns up the following.

  1. google recommends removing null properties from json when you send it. presumably to save bandwidth.
  2. Json.Net treats non existent properties as if they were null when deserialising

So essentially by missing off the property you are sending { "resources" : null } which is obviously different from an empty list.

Ergo, by the book its acceptable.

However!

Semantically, sending null and leaving a property off could be different. for example you want to update some data, but only properties you send. don't set stuff to null unless you specify { "property": null }

Furthermore you could be sending a list of key value pairs rather than an object

{
    "555 0123456" : "bob"
    "555 9876543" : "jane"
}

But these are edge cases, 99% of the time people will expect json to behave as if it's a serialised type with all parameters always present.

I would also guess that 99% of the time people expect lists never to be null and have a default value of empty list.

So, other that the outlined cases, having an endpoint behave differently based on different serialisation optimisations or interpretations of null just seems like a bad idea.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.