search

bluesky-social / bsky-docs

Bluesky API documentation
https://docs.bsky.app
Other
82 stars 71 forks source link

no record schema in the docs #120

Open yamarten opened 5 months ago

yamarten commented 5 months ago

Since there is no type definition for record in the API reference, important usage of the API is unclear. In particular, there is a concern that developers who do not use the official SDK will not be able to find a way to follow or like.

bnewbold commented 5 months ago

If I understand correctly, you are pointing out that record schemas don't end up in the docs.bsky.app HTTP reference: https://docs.bsky.app/docs/category/http-reference

The current location for those schemas, in machine-readable Lexicon language format (JSON) is in git: https://github.com/bluesky-social/atproto/tree/main/lexicons

at least for the app.bsky, tools.ozone, and com.atproto namespaces.

We'd love to get these included in docs.bsky.app, but haven't figured out a way to get the lexicon-to-openapi-to-docusaurus pipeline to get them to render.

yamarten commented 5 months ago

Yes, your understanding is correct.

Developers who have not read the atproto specification do not know enough about the concept of record and how to read lexicon, so they try to look for follow API in the HTTP reference.

Unfortunately, I don't have a solution to the pipeline problem. How about manually adding a list of links to the main record definitions on github as a first aid?