Adds nullability information to entities

[ornithocoder]

It helps developers building applications and libraries.

[dariusk]

I develop against APIs all the time and I'm not sure what "nullable" means. Does it mean "you can pass null without the API throwing an error"? How is "nullable" different from "optional"? Can you show me an example of existing API documentation with a similar "nullable" field? I'm just hesitant to approve because I've never seen this before.

I did google "api nullable" and found some discussion but a lot of it seemed to be around edge cases -- so much so that the API Blueprint description language didn't even support nullable fields until 2016.

[ornithocoder]

@dariusk

A nullable field is a payload field that can contain null. Some APIs simply remove null fields from the payload and in this case the field is said optional (but this is not the case for Mastodon).

Example:

// nullable name
{
   "name": null,
   "number": 42
}

// optional name
{
   "number": 42
}

For both Nullable and Optional, the field needs to be handled by the developer (or framework used by the developer) - since the type cannot be inferred - when deserializing the response.

Optional is easy to handle, and if the value is present in the payload, it is good to be used. Nullable field, on the other hand, cannot be used without sanitization.

For instance, check in_reply_to_id and reblog on the status response below:

{
    "id": 35768,
    "created_at": "2016-10-20T10:56:45.990Z",
    "in_reply_to_id": null,
    "reblog": null,
    "account": {
        "id": 1,
        "username": "Gargron",
        "acct": "Gargron",
        "display_name": "Eugen",
        "note": "Developer of Mastodon, a GNU social alternative: https://github.com/Gargron/mastodon",
        "url": "https://mastodon.social/users/Gargron",
        "avatar": "https://mastodon.social/system/accounts/avatars/000/000/001/large/J3IHut1v.png",
        "header": "https://mastodon.social/system/accounts/headers/000/000/001/medium/905578_10207278037490406_6099191809848953837_o.jpg",
        "followers_count": 398,
        "following_count": 350,
        "statuses_count": 1297
    },
    "media_attachments": [],
    "mentions": [],
    "uri": "tag:mastodon.social,2016-10-20:objectId=35768:objectType=Status",
    "content": "<p><a rel=\" noopener\" href=\"https://youtu.be/HBBwXAPNLr0\">youtu.be/HBBwXAPNLr0</a></p>",
    "url": "https://mastodon.social/users/Gargron/updates/17885",
    "reblogs_count": 0,
    "favourites_count": 0,
    "favourited": false,
    "reblogged": false
}

API.md even mention null for some fields in the payload:

[dariusk]

Thanks!