I’m coming late to this one, but have some thoughts. I don’t see any comments on the above PR so i’ll leave them here.
I think this is good as optional functionality to make API services self-documenting for developers and developer tooling. It could help developer tools like taproot (https://atproto.at/) do API calls and link to lexicon schemas (eg, https://lexicon.garden/). This is a fine addition to the lexicon community collection.
Often there is additional context you might want to know about a service or endpoint:
- which endpoints require what type of auth mechanism (this might be service-specific, not defined by the endpoint schema). and is auth required or optional (eg, maybe you get extra info if you authenticate)
- who is authorized to make API calls (eg, “any atproto account” or “just admins” or “some users”)
- what is the rate-limit story. maybe best left to HTTP headers?
The current proposal seems flexible enough to add any of that later on.
The related concept of have publishing service declaration records has bounced around, which would make services more discoverable (via indexing). Similar to community.lexicon.app.* but more generic? Maybe this has already been implemented somewhere, I can’t remember. There are already modality-specific variations of this: eg a feedgen declaration does basically this. I think having separate modality-specific records types for that is a good pattern.
I do think all this should be strictly optional though, and not an operational norm. This API came up in a separate thread as being a requirement, and I want to address that more broadly.
I don’t think the ecosystem should use a mechanism like this in production to detect or negotiate features or compatibility at runtime.
The primary reasons for that is complexity of implementation and efficiency of operation. It requires extra round-trips, and results in complex logic.
As a smaller reason, generating and maintaining reliable API endpoint listings isn’t easy in all situations. Not all web frameworks have introspection. Service hostnames aren’t always a single monolithic piece of software: it is pretty common to have a load balancer direct different endpoints to different backend services. With enough effort things are possible, but I don’t think we should expect folks to do this all the time.