Document read-only endpoints that don't require auth

[gaearon]

We need to:

• Make it clear how obtain a bearer token (the docs are currently vague about this)
• Split APIs into read-only and requiring auth. Make that distinction clear. Possibly even with icons in the sidebar
• Integrate this information into the runnable HTTP widget. Make it easy to get bearer token right there for any API call or, for publicly available APIs, not require it at all
• Make sure the instructions and code snippets for any public API don't force you to enter the token. Just like our PWI is able to access those endpoints without logging in

[bnewbold]

which APIs do and don't require auth: we've discussed adding this a machine-readable metadata in the Lexicons themselves, which would help a bunch. We would want to enumerate the specific OAuth scopes required, and have a clear set and naming for the "network services" which implement the endpoints, so we probably don't want to block on this protocol work getting finished.

In a more informal way, I started adding a few annotations in description fields. but we could also just split up the docs or add tags or something to make it easier.

But maybe even more than "which actually don't require auth" it would be most helpful to have a currated set of public endpoints that are recommended and easy to work with.

[gaearon]

What's the general flow for hitting the endpoint without auth? I think the MVP here is just to explain it somewhere since right now the docs make it feel like you have to always log in.

[bnewbold]

ahhhh, you know, yeah, we really should document this and haven't, both for beginners and experienced devs.

the main stuff we are both probably thinking about are the Bluesky (app.bsky.*) endpoints, which are best hit on the public-optimized version of the API: https://public.api.bsky.app.

some of the lower-level stuff can go to relay (https://bsky.network) or individual PDS instances (hostname varies).

some low-hanging fruit:

# fetch single profile by handle (or DID)
http get "https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile?actor=bnewbold.net"

# fetch author feed by handle (or DID); this method has a few interesting query params for filtering
http get "https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?actor=bnewbold.net"

# search posts
http get "https://public.api.bsky.app/xrpc/app.bsky.feed.searchPosts?q=moss"

# search accounts/profiles
http get "https://public.api.bsky.app/xrpc/app.bsky.actor.searchActors?q=london"

# get a public feed; this does NOT currently work (requires auth) but we should probably make it work (make auth optional), if the upstream feed generator supports it (and have caching in the path)
http get "https://public.api.bsky.app/xrpc/app.bsky.feed.getFeed?feed=at%3A%2F%2Fdid%3Aplc%3As6jnht6koorxz7trghirytmf%2Fapp.bsky.feed.generator%2Fatproto&limit=30"

[boly38]

my 2 cents : doc and bearer token - first @gaearon bullet - has a dedicated issue : #62