tumblr / docs

Tumblr's public platform documentation.
Apache License 2.0
108 stars 26 forks source link

Add missing fields to blog info #85

Closed yeSpud closed 2 years ago

yeSpud commented 2 years ago

There are a few fields that still have missing descriptions. Feel free to fill those in.

cyle commented 2 years ago

Hello @yeSpud -- unfortunately we can't accept this pull request, thank you for the suggestion though. While most of these fields are publicly available, they are intentionally not publicly documented. But there are indeed some gaps that we can improve in our documentation.

yeSpud commented 2 years ago

Is there a reason why these fields are to remain undocumented?

marcustyphoon commented 2 years ago

I assume it is because Staff is not committing to keeping them the same, so developers using them would hav to take responsibility for updating their applications quickly if those fields were to vanish or change.

yeSpud commented 2 years ago

There are some keys / values that do seem important to document though

NSFW blogs being an example

cyle commented 2 years ago

Is there a reason why these fields are to remain undocumented?

Two primary reasons: first, what @marcustyphoon said above, which is that we're not going to publicly commit to them being reliable. We have fields and objects in the API that are in flux because they're in development, and they'll get documented publicly once they're ready to be used publicly.

Second, some fields may happen to be publicly visible and we actually do want to keep them reliable, but we don't want them used publicly by third party clients. There are a few fields that only our Official clients understand how to use, and we purposefully want to keep it that way for now, hence they're not publicly documented. Like the first case, when those fields are ready to be used publicly, we'll document them publicly.