🔗 API concepts missing proper links

[JFWooten4]

These are the local pages corresponding to the docs we changed:

• http://localhost:3000/docs/data/apis/horizon/api-reference/get-offer-by-offer-id
• http://localhost:3000/docs/data/apis/horizon/api-reference/list-trade-aggregations
• http://localhost:3000/docs/data/apis/horizon/api-reference/list-all-assets
• http://localhost:3000/docs/data/apis/horizon/api-reference/list-all-claimable-balances
• http://localhost:3000/docs/data/apis/horizon/api-reference/retrieve-a-ledger
• http://localhost:3000/docs/data/apis/horizon/api-reference/list-strict-receive-payment-paths
• http://localhost:3000/docs/data/apis/horizon/api-reference/list-strict-send-payment-paths
• http://localhost:3000/docs/data/apis/horizon/api-reference/submit-async-transaction

[Copilot]

Pull request overview

Updates Horizon OpenAPI endpoint descriptions (and the generated API reference pages) to include inline links to the relevant “concept” documentation within this docs repo, improving navigability and reducing reliance on hard-coded external URLs.

Changes:

• Added internal doc links to key concepts (assets, ledgers, offers/trades, claimable balances) in multiple endpoint descriptions.
• Replaced an external URL in the async transaction submission description with an internal relative link to the “Retrieve a Transaction” endpoint doc.
• Regenerated/updated the bundled OpenAPI spec and affected generated .api.mdx pages to reflect the new link text.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
openapi/horizon/components/endpoints/transactions.yml	Switches async submission description to link internally to the “Retrieve a Transaction” endpoint doc.
openapi/horizon/components/endpoints/tradeAggregations.yml	Adds an internal concept link for “trade” in the endpoint description.
openapi/horizon/components/endpoints/paths.yml	Links strict send/receive path endpoints to the corresponding operation concept docs.
openapi/horizon/components/endpoints/offers.yml	Adds an internal concept link for “offer” in the endpoint description.
openapi/horizon/components/endpoints/ledgers.yml	Adds an internal concept link for “ledger” in the endpoint description.
openapi/horizon/components/endpoints/claimableBalances.yml	Adds an internal concept link for “claimable balances” in the endpoint description.
openapi/horizon/components/endpoints/assets.yml	Adds an internal concept link for “assets” in the endpoint description.
openapi/horizon/bundled.yml	Updates bundled OpenAPI output to include the new linked descriptions.
docs/data/apis/horizon/api-reference/submit-async-transaction.api.mdx	Updates generated page content/frontmatter to use the new internal link to “Retrieve a Transaction”.
docs/data/apis/horizon/api-reference/retrieve-a-ledger.api.mdx	Updates generated page content/frontmatter to link “ledger” concept doc.
docs/data/apis/horizon/api-reference/list-trade-aggregations.api.mdx	Updates generated page content/frontmatter to link “trade” concept doc section.
docs/data/apis/horizon/api-reference/list-strict-send-payment-paths.api.mdx	Updates generated page content/frontmatter to link strict-send operation concept doc.
docs/data/apis/horizon/api-reference/list-strict-receive-payment-paths.api.mdx	Updates generated page content/frontmatter to link strict-receive operation concept doc.
docs/data/apis/horizon/api-reference/list-all-claimable-balances.api.mdx	Updates generated page content/frontmatter to link claimable balances guide.
docs/data/apis/horizon/api-reference/list-all-assets.api.mdx	Updates generated page content/frontmatter to link assets concept doc.
docs/data/apis/horizon/api-reference/get-offer-by-offer-id.api.mdx	Updates generated page content/frontmatter to link offer/orders concept section.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[briwylde08]

Hey @JFWooten4! Thanks for all these PRs. Can you tag me as a reviewer whenever each one is ready for review? Then I can get them assigned out. Just don't want to review them before they're ready.

[JFWooten4]

Hey Bri! Thanks, that makes sense. It doesn't look like I can tag you through the formal reviewer selector since I don't have write access to the repo. The docs say I "will need write access to the repository" to use that reviewer gear icon.

[briwylde08]

Ah okay! Well maybe just tag me in a comment and let me know!

[JFWooten4]

Yeah, so this is something we ran into a while back in WhyDRS/Taking-Stock#14. The challenge for us was originally notifications of changes across a bunch of different repos. Admittedly far fewer than StellarOrg, but still it was enough to leave a minor PR unnoticed for months on my end. Something similar happened with #1099.

Our solution was to install a Discord bot that connected to the org webhook to stream new actions. This gave us a live feed and notification of contributor activity. I'm not sure what the equivalent would be in Slack, but I'm sure it exists. After that, there were much more eyeballs on the changes, and we started getting some of the spontaneous community review help we saw in #723 (review).

I don't know exactly how to move forward with this, because all of my open PRs are ready for review. I've taken effort to carefully mark duplicative bulk items as Drafts only. So the way I read this is go through and mass tag you in everything I have open. That has a few downstream challenges in my mind.

First, it places you as a central actor organizing review efforts. Which is not to say that you're not great at it! But it is functionally limited, as that leaves the bandwidth of the whole repo bottlenecked and on your shoulders. I don't think that's fair or nice, because people deserve breaks.

I will admit that I exclusively work in flat organizations without the hierarchy of directive management. 😅 So these Microsoft-centric reviewer and assignee concepts already stand out as really foreign to how I operate. But our DUNA has accepted that platform for its network effects despite these hierarchical artifacts. You should've seen our hours of heated-ish discussion over whether or not to use org team roles!

I've interpreted the Foundation's public statements to prefer decentralization when possible. It's one of the core alignment items for now CAPs, to "support decentralization wherever possible, but not at the expense of the majority of its values." And I was quite inspired by the original vision of distributing lumens to the world, and then later allocating them to public charities. I could cite a bunch of specifics, but I'll just say broadly it has seemed that decentralizing our development efforts directly spells for increased network use.

I remember Tyler discussing his contributions to a new page on the old Stellar Podcast. He was so happy to have made a difference in the network documentation. It is a good feeling, and I think we've seen that with the over 100 contributors from disparate corners of the network. This repo is an important asset with value that helps users far and wide—heck, just look at all the translations offered!

I work in the corporate world. Startups and even mature enterprises don't get big by holding onto power or resources. They learn to delegate, share stock, and expand horizontally to cover more ground. I see these docs like a founding Culver's at a critical breaking point of overcrowding, just begging for another local franchise.

I've proposed some clear changes based on years of regulatory analysis and project planning related to the DEX. They were deemed out-of-scope and branded as "ideas" because the Foundation doesn't see the point in working on them. Tomer has made it very clear he does not value the same market principles our nonprofit champions. I am not unique in wanting to build improvements in repos like the docs, but lacking the internal power or sway to affect Foundation dev time allocation.

All that is totally fine, healthy even. You guys have your goals, and the rest of the ecosystem has theirs. The challenge I've seen is that external objectives stall without the attention or funding needed to pick them up and above a solo dev. I would like to bring more of our team onto the network side to build out the docs and improve the protocol. I know of others in a similar position.

If these efforts were to reach their full potential, the network would presumably grow quite large. The efforts would also greatly increase the number of contributions to the Foundation repos from outside parties. Emir said that he'd love to see this because the Foundation can't just do everything, when we talked in an ecosystem space about the YieldBlox bailout. That point there is exactly the kind of thing I've been trying to plainly explain away with my SDEX page update.¹

Anyway, back to the point of relevance, more contributors => more PRs => more review burden. Eventually that can overload even the best of central teams. And I just don't want to see that happen with something as important as the developer documentation. Because I've seen how contributions can dry up when they come with too much admin dominance.

I get that some people might operate best by directly pinging you about new suggestions. I do not generally work with such people. I've tried to make my contributions very clear with the drafts so that collaboration happens on overlapping interests, or by just not pushing through the three branches before this PR which weren't ready at all. I think too #2387 framing out a simple add, because a lot of us are just used to the more internet-native drafting of building what's needed and iterating together over time without asking anyone.

It'd be great if I could just tunnel into his PR and rebuild the routes to add the new refs. And the same thing goes with my pages. I'll be the first to admit #2383 really could've started as a more collaborative issue discussion. But I fixed everything outstanding there within 79 minutes of the AI review.

So yeah, they are all really clean and scoped PRs that I'd like processed just as any other open contribution. If there's anything specific I can do on them to improve or streamline, please by all means in the process of reviewing. And it'd be cool to chat more about these structural points given how much the Mandate allocates for active developer support. We have quite aligned interests because the TAD systems I've worked on for years only grow with the expansion of the network.

Footnotes

1. Those improvements would also show up in less market permissioning such as Franklin Templeton's unnecessary use of heavy SEP-8 custodianship. As their SEC filings state, users do not have unrestricted interoperable network access to funds, largely given BENJI on the DEX needs more docs. I referenced this point specifically in my discussions with Examiner staff last year. This provides me a unique internal perspective to review DEX-related PRs which cannot be easily exported from my organizations. ↩

[ElliotFriend]

I'd advise against adding these kinds of ../../relative/links.mdx into the OpenAPI spec files. The spec files are more useful than just generating the docs for these APIs, and they need to make sense in a context outside of the docs site. As this PR currently stands, those relative links would be actively confusing to readers/renderers. It might even cause some spec rendering engines to crash

[JFWooten4]

Oh, I did not think about external imports of the OpenAPI spec files! Very good point.

I based my relative linking on the "same directory" logic from #453. To confirm, are you saying you'd rather use ../link/to/file in the YMLs for cross-repo support?

[ElliotFriend]

In any of the specfiles in /openapi or /openrpc directories, we're probably best suited to use full https://developers.stellar.org/docs/whatever/path URLs, if we want to add them. That way someone viewing the specfile in an IDE, for example, can get to the correct resource.

It's a little confusing, I know, and I thought we had a note in one of those directories, but I might be remembering an internal Slack conversation, or something instead.

[JFWooten4]

There's a slight reference to the file separation in the data CONTRIBUTING guide, but I don't remember the docs themselves laying that concept out. Maybe in the package for one of the SDKs. The only other main-ish page doesn't detail anything about URLs. Something to add into the contribution combination.