76

I'm in the process of designing and developing a RESTful API. I'm taking a pragmatic, resource oriented approach to the API (resource oriented, uniform interface, addressability, but no real HATEOAS). One point I'm not sure about though is how to approach null values in objects.

Should I include fields with null values in the APIs responses?

Example:

{
    "fieldA": "AAA",
    "fieldB": null
}

Or, should I just leave out these fields altogether if the system has no data for these fields?

Example:

{
    "fieldA": "AAA"
}
Dennis Laumen
  • 3,163
  • 2
  • 21
  • 24
  • 2
    Related: https://stackoverflow.com/questions/9619852, https://stackoverflow.com/questions/11003424 – tkruse May 21 '18 at 05:28

2 Answers2

42

There was a discussion about this recently on API-Craft. The general consensus was there is potentially a semantic difference between the omission of a value, versus an inclusion of a null value.

If there is no semantic value to be gained for your specific use case, then I would say look at your target consumers of the API, and think about whether omitting the value will cause them problems.

Pete
  • 11,313
  • 4
  • 43
  • 54
  • 7
    Thanks! I've decided to go for the `null` approach as it indeed makes the most sense. I have several representations for our logical entities and adding a `null` value more clearly communicates to clients that the field is a part of the representation but no data is available for that field. In hindsight, this was a real _d'oh!_ moment (it just makes sense). – Dennis Laumen Mar 29 '13 at 08:12
  • Judging by questions on stackoverflow, most iOS programmers are not clever enough for this, and null values will lead to crashes. Not saying that you're wrong, but having values that may be null _very rarely_ would be a problem. At least for testing, you need to be able to produce data that is littered with null's so you don't have bad surprises later. – gnasher729 May 27 '15 at 10:53
  • 7
    But I guess then also omitting the value would cause crashes in these iOS applications? I can't really see the difference regarding this. – Daniel Rotter Jul 15 '15 at 07:47
  • omitting field in iOS do not crash the app, get a on object for key from a Dictionary is optional value. So the programmer know it can be nil – Scinfu May 25 '17 at 15:33
  • I decided to strip nulls as default on my routes to save bandwidth. I see no point in transfering a bunch of field names with nothing in them. All my routes can take a query param in case someone needs the null values (?includeNullValues=true), mostly used for testing/debugging. I also have an exception list of field names per route so can I leave the null value in the response for given fields, if the nulls do carry important information. – Michael Nov 06 '17 at 10:42
  • if you have ever used a rest payload that made you fish for property existence, if (var in obj) then you know how painful it is. I think it also affects what constitutes a breaking change, and when an api version is required. If properties can mysteriously be removed, devs can use this to deprecate things which are truly breaking. – httpete Jul 15 '19 at 15:23
32

There is no clear winner. And because there is not, clients should never technically depend on any convention about this, clients should not expect either shape.

  • removing null values to reduce bandwidth usage is commonly not justified (unless the number of null fields is large and the bandwidth noticeably suffers).
  • removing null values to allow human readers to more easily see actual values is not commonly justified, APIs are not man-machine interfaces
  • keeping null values to allow human readers to more easily see document structure is not commonly justified, APIs are not man-machine interfaces, and API responses are not API documentation
  • keeping null values to allow dirty clients to parse the json in specific ways is commonly not justified, clients should be written cleanly as tolerant readers
  • keeping null values only where the corresponding create method (POST/PUT) requires explicit passing of null would make sense, but is commonly difficult to achieve
  • keeping the output same as the request during creation could make sense when each document has its own owning client, but is commonly difficult to achieve
  • A special case to consider is partial responses triggered by something like ?fields=foo,bar where returning nulls for all other fields seems a bit counter-intuitive
tkruse
  • 10,222
  • 7
  • 53
  • 80
  • 2
    Helpful if opinionated response. I don't agree with `keeping null values to allow human readers to more easily see document structure is not commonly justified`. API responses _are_ documentation, de facto. But overall this is a good list of things to consider. Kudos to you for capturing the summary succinctly in the first sentence. – Cheeso Jul 25 '22 at 15:13