Missing documentation - /api/app-bsky-feed-get-posts

[blowdart]

https://docs.bsky.app/docs/api/app-bsky-feed-get-posts is missing documentation on the following

Author - all properties Record - all properties except images (but the images array possible values has an HTML encoded <) Viewer - all properties Threadgate - all properties.

[bnewbold]

ugh! thanks for reporting.

as some context, we are thinking about re-writing the entire API reference docs system to be Lexicon-native, and automatically work with all Lexicons in the ecosystem (eg, whtwnd, smokesignals, etc). this means we probably aren't going to invest too much time in the current API reference docs, though we should fix bugs like this one.

[blowdart]

I mean sure, except the lexicon has lacking documentation too, so it won't improve anything there 🤷‍♂️

[bnewbold]

ah, I see, you are looking for description fields in the Lexicon itself?

[blowdart]

Yes. I want to document my object properties with what they represent/mean, and a lot of the time I'm guessing.

Rant follows :)

The lexicon docs make it worse, because it's more of an ideological explanation that a true description of what the APIs take, and when you finally find the schema repo the properties aren't documented there either.

https://atproto.com/specs/lexicon doesn't discuss what you need to call an API at all. Finding the actual schemas from the docs site is hard, hence looking at the API docs. Sometimes if you're lucky you'll find a link to, say, https://github.com/bluesky-social/atproto/blob/main/lexicons/app/bsky/feed/post.json and then you release that's where the schemas are.

It doesn't help that in the API docs terms get reused, despite the object shapes the api/underlying schema objectbeing very different. Viewer is a good example, the Viewer in a Thread Gate is very different to the Viewer in a notification, or in a feed post but the docs just wave hands and describe them as viewer, and then you end up ploughing through the lexicons and your class names end up being quite different to what you'd think from the api docs.

If lexicon and schema are first class concept, then they should be right there on the docs home page, not buried away up and under the AT Proto guides, with luck linking you to the atproto repo, where you might see lexicons and then figure it out.

Now I realise a part of this is my problem, being in a strongly typed language trying to model a schema/object model that very much relies on being dynamic, and partly it's because I want to go with my language's best practices around documentation, but y'all just make it so damn hard.