Document /headers/original/missing.png in the header field

[nikclayton]

No description provided.

[vercel]

@nikclayton is attempting to deploy a commit to the Mastodon Team on Vercel.

A member of the Team first needs to authorize it.

[trwnh]

i don't think this is necessary to clarify?

[nikclayton]

i don't think this is necessary to clarify?

I think it is. I wasted a bunch of time yesterday investigating why a null check in some code wasn't working, only to discover that the value coming back from the API for a missing value was, completely inexplicably, and in contrast to the rest of the api, not null.

[trwnh]

it's already non-nullable in the docs though. idk why you would expect it to be null. if something can be null, it will explicitly be marked "nullable".

[nikclayton]

it's already non-nullable in the docs though. idk why you would expect it to be null. if something can be null, it will explicitly be marked "nullable".

1. It would be clearer if non-nullable was also explicitly mentioned (although that is orthogonal to this PR)
2. Either way, the fact that "This profile does not have a header image" is not indicated with null, or the empty string, or the field not being present in the response, but is instead represented by an undocumented magic string is extremely surprising, and as the developer of a Mastodon client leaves me asking questions like:

• Is this magic string part of the API surface, or is it free to change at any time?
• Is this magic string /headers/original/missing.png, or /original/missing.png, or /missing.png?
• Are other Mastodon-compatible servers free to return a different magic string, or the empty string, instead?
• What other parts of the API rely on undocumented magic strings?

API documentation should be complete and unambiguous. This PR incrementally improves the Mastodon API documentation towards this goal.

[trwnh]

it's not a "magic string", it's an actual image that can be resolved and used as a placeholder. yes, the server may return any path it wants; the current guarantee is that it is a valid image url.

"nullable" is the exception, and non-nullable is the general rule. the type listed for each property is the type that will be returned. if the type lists null as a possible return value, then this is highlighted so that developers may take care to avoid null pointer exceptions. otherwise it should be safe to proceed and use the value as-is.

[nikclayton]

it's not a "magic string", it's an actual image that can be resolved and used as a placeholder. yes, the server may return any path it wants; the current guarantee is that it is a valid image url.

It is a magic string, because it's the only indicator that the user has not uploaded their own header or avatar image. In order, the absence of the field, a null value, or the empty string would all be better implementations than this, and more

Consider a frontend that wants to allow the user to modify their header image by providing two options:

1. Delete image
2. Upload new image

The "Upload new image" option is always valid.

The "Delete image" option should only be shown to the user if they have an image to delete, and to test that you have to check against the magic /headers/original/missing.png string. Which is undocumented.

And if different servers are free to return their own string it's even worse.

Finally, I note that other parts of the documentation do take care to document the magic string, like https://github.com/mastodon/documentation/blob/master/content/en/methods/media.md

[github-actions]

This pull request has merge conflicts that must be resolved before it can be merged.