Should we return an empty string or null for optional fields left blank

[Guilherme Gössling]

Don't think one can be considered the 'correct way', but was wondering
if there is a consensus or standard on how we should present blank
values on an API response.

All the GET calls to my API return false as that is the value being
returned by MySQL for empty fields (set to NULL as default).

e.g. GET /users returning null for optional fields left blank.
[{"user_id":"4","first_name":John,"last_name":null}]

[Dolf Schimmel]

Although we usually produce XML with our API's we had the same issue. 

Were we going to return <element xsi:nil="true" /> or were we to just going to leave the element out completely?

We finally opted to use the xsi:nil="true" notation:

* Using false wasn't an option since 'false' represents an actual (boolean) value.
* Leaving the element out completely made it harder for clients to parse the responses (potentially for each field the client would first have to check if it even exists)

* xsi:nil actually represents a nil value, something that simply isn't. Which is exactly the kind of thing we're wanting to represent.

Translating this to json, I would opt for simply going with [{"field":null}]. Again, simply because 'null' represents a non-value, whereas any other kind of thing represents some value.

Just my 0.02 $

Dolf

-- Freeaqingme

2012/4/16 Guilherme Gössling <ggu...@gmail.com>

[Guilherme Gössling]

Thanks for the response Dolf.

Sorry, In my previous post I mentioned we return false, but we don't,
we always return null as you can see in my example above.

I agree with you in not leaving the field out, as that would cause the
response to be quite inconsistent and unpredictable.
For now I'll leave it as it is, returning null.

Does anyone know what the big guys are doing regarding this?

Guilherme

[Dale McCrory]

JSON serializers are a lot more forgiving than XML. Therefore having a
bunch of {"field":"null"} JSON objects is pretty ugly and adds to the
bandwidth (which is why you use JSON).

We recently had the debate at my company of do we force order on JSON
or not. The answer was NO!! because clients are free to put whatever
sort order needed into the JSON and ordering of results is an XML
Schema (WSDL) solution / opportunity that JSON simplifies for clients.
I put the Null value example in the same category of issue.

Dale

2012/4/16 Guilherme Gössling <ggu...@gmail.com>:

[Matthew Bishop]

Setting the field to null is undiscoverable:

jsObject['field'] will return null if the field is marked null or if
the field doesn't exist.

Better to return an empty string if you want them to know about the
field.

[Jack Repenning]

On Apr 16, 2012, at 2:45 PM, Dale McCrory wrote:

> I put the Null value example in the same category of issue.

Agreed. Though, the difference between {"field":"null"} (the string n, u, l, l) and {"field":null} (the null value) is still worth some attention ;-)

Jack Repenning

Things should be made as simple as possible --
and no simpler!
-- Albert Einstein

[Arlo Belshee]

I'd answer the question of whether to order JSON properties is "that depends." Two examples, one which clearly requires each answer:

Many JSON libraries, especially in dynamic languages, expose JSON objects as dictionaries. Thus, there is no way for a JSON producer to define order.

Many applications deal with infinite streams of data. Some of these have trees that can be arbitrary depth. Thus, they need stream serialization. Since there are app-level concerns, they need to guarantee that some information always happens before the first possibly-recursive part of the payload.

In our case, we made the ordering constraint optional and added a header to indicate whether the content was "stream parsable" (passed our ordering constraints). We didn't fully-order, but we did find places where certain fields needed to appear first. We also added a way to request that a response be given in stream order if possible (in many cases it is possible but more expensive).

This worked pretty well. The ordering allows a performance & scaling optimization. But if you know that you won't be doing things at massive scale, then you can ignore the constraints and just buffer everything.

Arlo

[Arlo Belshee]

In OData, we allow the use of both static and dynamic types. When declaring a payload entity, you can say that it is fully static. Or you can say that it has a particular set of static properties and an infinite number of additional dynamic ones.

When serializing, a NULL dynamic property is defined to be exactly the same as a missing one. So we elide them.

All static properties are always represented. This makes it easier on libraries that choose to direct-map the payload to a static type.

This works pretty well for us, but requires that the server be able to declare its type system in a machine-readable fashion.

Arlo

[Dolf Schimmel]

>> Setting the field to null is undiscoverable:

>> jsObject['field'] will return null if the field is marked null or if
>> the field doesn't exist.

>> Better to return an empty string if you want them to know about the
>> field.

Then you are assuming that all of your clients will be made up of Javascript. It doesn't hold truth per se in other languages (like PHP). Also, an empty string denotes a clear value (that happens to be empty nonetheless), whereas null clearly defines the fact that the value of the property is unkown.

Dolf

-- Freeaqingme

[sune jakobsson]

And of course if all fields are empty or null in the response, this should be signalled at HTTP level with 204 No Content, telling the client that the resource exists, but is not populated with data.

Sune