I am trying to understand how the interaction between ATProto entities works at the most basic level, which I suppose are HTTP(S) requests. I’d like to start with the PDS, which seems to be the most basic entity because it could in principle exist in isolation. I should be able to operate a PDS like a Web server, right? I actually expect a PDS to be a Web server, accessible via an API. But I haven’t been able so far to find documentation for this API. Or, better yet, a tutorial that doesn’t use any additional tool layer. Can I add, retrieve, and delete data from a PDS just via curl from the command line? Is there any tutorial explaining this?
more info here The AT Stack - AT Protocol Docs - AT Protocol
Yes, you can curl things, the goat CLI tool is atproto specific, not http specific, but does similar things GitHub - bluesky-social/goat: Go AT protocol CLI tool · GitHub
There are a number of bash scripts bundled with the Bluesky TypeScript PDS that are in fact just curl requests you can look at pds/pdsadmin at main · bluesky-social/pds · GitHub
The role of the PDS is account hosting, which also includes auth and related things.
Broadly speaking, atproto is a distributed system. You can totally just fetch from a PDS and store stuff in your account. Running a PDS, you can choose which relays it connects to, etc etc
You may also be interested in Red Dwarf, which is an atproto client which doesn’t have a centralized appview, but just connects to PDS directly whey.party/red-dwarf at main
Thanks for those pointers!
I had already found the guides at atproto.com, but they don’t go into the details of the API.
goat is what I have been using so far to explore the PDS layer. Now I want to dig one level deeper.
The bash scripts look like a good start for that!
Right. And rather than an API for a specific piece of code – although of course the Bluesky reference PDS implements certain endpoints – it’s at:// URIs and XRPC calls (for account stuff) and then for data, related Lexicon types, as specified in the protocol.
Here are some specific doc pages that might be helpful:
- http api / xrpc HTTP API (XRPC) - AT Protocol
- at uri scheme AT URI scheme (at://) - AT Protocol
- reads and writes Reads and Writes - AT Protocol Docs - AT Protocol (which means connecting to an account repo which lives on some PDS)
Ahhh…. thanks, that was the missing piece! The API is expressed in a separate protocol layer, which is then mapped to HTTP. That makes perfect sense, but I haven’t seen it mentioned yet, in spite of reading quite a bit of ATProto docs.