Add API Migration Guide for Horizon to RPC

config/sidebars.ts

@@ -29,6 +29,12 @@ const sidebars: SidebarsConfig = {
     { type: 'ref', id: 'data/galexie/README', label: 'Galexie'},
     { type: 'ref', id: 'data/data-indexers/README', label: 'Data Indexers'},
     { type: 'ref', id: 'data/oracles/README', label: 'Oracles'},
+    { type: 'html', value: '<small>Migration Guides</small>', defaultStyle: true, className: 'networkMenuHtmlItem'},
+    {
+      type: "doc",
+      id: "data/migrate-from-horizon-to-rpc/README",
+      label: "Horizon to RPC"
+    },
   ],
   tools: [
     {

docs/data/migrate-from-horizon-to-rpc/README.mdx

@@ -0,0 +1,123 @@
+---
+title: Migrate from Horizon to RPC
+sidebar_position: 0
+---
+
+Applications using [Horizon's REST-like API] will need to be updated to use the [RPC JSON-RPC API] when migrating from [Horizon] to [RPC]. This guide provides an overview of the key differences between the two APIs and how to migrate your application.
+
+## Request / Response Format
+
+Horizon's REST-like API uses HTTP methods and status codes to communicate with clients. Responses are JSON in the HAL format. See [Horizon's Response Format].
+
+RPC's JSON-RPC API uses JSON-RPC 2.0 to communicate with clients. Requests to the API are JSON objects that contain one or more method invocations. Responses are also JSON objects that contain a result for each invocation in the request. See [JSON-RPC].
+
+Both formats utilise JSON for the overall structure which are relatively simple and do not require any special client code, although there are client [SDKs] available. Some values contained within are XDR encoded and can be decoded using Stellar [SDKs].
+
+## Endpoint Mapping
+
+Applications that use the following Horizon endpoints can typically migrate directly to the RPC using the referenced methods.
+
+Endpoints without mappings do not have a direct replacement in the RPC API. To build similar functionality in an application, take a look at other [Data] products.
+
+| Horizon Endpoint | RPC Method |
+| --- | --- |
+| [`GET /`] | [`getLatestLedger`] [`getVersionInfo`] [`getHealth`] [`getNetwork`] |
+| [`GET /ledgers`] | [`getLedgers`] |
+| [`GET /ledgers/{seq}`] | [`getLedgers`] |
+| [`GET /ledgers/{seq}/transactions`] | [`getTransactions`] |
+| [`GET /ledgers/{seq}/operations`] | [`getTransactions`] |
+| [`GET /ledgers/{seq}/payments`] | [`getEvents`] ⚠️ |
+| [`GET /ledgers/{seq}/effects`] | [`getEvents`] ⚠️ |
+| [`POST /transactions`] | [`sendTransaction`] |
+| [`POST /transactions_async`] | [`sendTransaction`] |
+| [`GET /transactions`] | [`getTransactions`] |
+| [`GET /transactions/{hash}`] | [`getTransaction`] |
+| [`GET /transactions/{hash}/operations`] | [`getTransaction`] |
+| [`GET /transactions/{hash}/payments`] | - |
+| [`GET /transactions/{hash}/effects`] | - |
+| [`GET /operations`] | [`getTransactions`] |
+| [`GET /operations/{id}`] | - |
+| [`GET /operations/{id}/effects`] | - |
+| [`GET /fee_stats`] | [`getFeeStats`] [`simulateTransaction`] |
+| [`GET /accounts`] | - |
+| [`GET /accounts/{address}`] | [`getLedgerEntries`] |
+| [`GET /claimable_balances`] | - |
+| [`GET /claimable_balances/{id}`] | [`getLedgerEntries`] |
+| [`GET /claimable_balances/{id}/transactions`] | - |
+| [`GET /claimable_balances/{id}/operations`] | - |
+| [`GET /liquidity_pools`] | - |
+| [`GET /liquidity_pools/{id}`] | [`getLedgerEntries`] |
+| [`GET /liquidity_pools/{id}/transactions`] | - |
+| [`GET /liquidity_pools/{id}/operations`] | - |
+| [`GET /liquidity_pools/{id}/effects`] | - |
+| [`GET /liquidity_pools/{id}/trades`] | - |
+| [`GET /offers`] | - |
+| [`GET /offers/{id}`] | [`getLedgerEntries`] |
+| [`GET /offers/{id}/trades`] | - |
+| [`GET /payments`] | [`getEvents`] ⚠️ |
+| [`GET /effects`] | [`getEvents`] ⚠️ |
+| [`GET /trades`] | [`getEvents`] ⚠️ |
+
+:::warning
+
+The [`getEvents`] method is not a direct replacement for Horizon's endpoints. The method returns a stream of events that in the current protocol only include events from contracts. In the near future as a result of [CAP-67] this method will be expanded to include events from non-contract operations.
+
+:::
+
+[CAP-67]: https://github.com/stellar/stellar-protocol/blob/master/core/cap-0067.md
+[Horizon]: horizon
+[RPC]: rpc
+[Horizon's REST-like API]: horizon/api-reference
+[Horizon's Response Format]: horizon/api-reference/structure/response-format
+[RPC JSON-RPC API]: rpc/api-reference
+[JSON-RPC]: rpc/api-reference/json-rpc
+[Data]: ../data
+[SDKs]: ../tools/sdks/library
+[`GET /`]: horizon/api-reference
+[`GET /ledgers`]: horizon/api-reference/list-all-ledgers
+[`GET /ledgers/{seq}`]: horizon/api-reference/retrieve-a-ledger
+[`GET /ledgers/{seq}/transactions`]: horizon/api-reference/retrieve-a-ledgers-transactions
+[`GET /ledgers/{seq}/operations`]: horizon/api-reference/retrieve-a-ledgers-operations
+[`GET /ledgers/{seq}/payments`]: horizon/api-reference/retrieve-a-ledgers-payments
+[`GET /ledgers/{seq}/effects`]: horizon/api-reference/retrieve-a-ledgers-effects
+[`POST /transactions`]: horizon/api-reference/submit-a-transaction
+[`POST /transactions_async`]: horizon/api-reference/submit-async-transaction
+[`GET /transactions`]: horizon/api-reference/list-all-transactions
+[`GET /transactions/{hash}`]: horizon/api-reference/retrieve-a-transaction
+[`GET /transactions/{hash}/operations`]: horizon/api-reference/retrieve-a-transactions-operations
+[`GET /transactions/{hash}/payments`]: horizon/api-reference/retrieve-a-transactions-payments
+[`GET /transactions/{hash}/effects`]: horizon/api-reference/retrieve-a-transactions-effects
+[`GET /operations`]: horizon/api-reference/list-all-operations
+[`GET /operations/{id}`]: horizon/api-reference/retrieve-an-operation
+[`GET /operations/{id}/effects`]: horizon/api-reference/retrieve-an-operations-effects
+[`GET /fee_stats`]: horizon/api-reference
+[`GET /accounts`]: horizon/api-reference/list-all-accounts
+[`GET /accounts/{address}`]: horizon/api-reference/retrieve-an-account
+[`GET /claimable_balances`]: horizon/api-reference/list-all-claimable-balances
+[`GET /claimable_balances/{id}`]: horizon/api-reference/retrieve-a-claimable-balance
+[`GET /claimable_balances/{id}/transactions`]: horizon/api-reference/cb-retrieve-related-transactions
+[`GET /claimable_balances/{id}/operations`]: horizon/api-reference/cb-retrieve-related-operations
+[`GET /liquidity_pools`]: horizon/api-reference/list-liquidity-pools
+[`GET /liquidity_pools/{id}`]: horizon/api-reference/retrieve-a-liquidity-pool
+[`GET /liquidity_pools/{id}/transactions`]: horizon/api-reference/lp-retrieve-related-transactions
+[`GET /liquidity_pools/{id}/operations`]: horizon/api-reference/lp-retrieve-related-operations
+[`GET /liquidity_pools/{id}/effects`]: horizon/api-reference/retrieve-related-effects
+[`GET /liquidity_pools/{id}/trades`]: horizon/api-reference/retrieve-related-trades
+[`GET /offers`]: horizon/api-reference/get-all-offers
+[`GET /offers/{id}`]: horizon/api-reference/get-offer-by-offer-id
+[`GET /offers/{id}/trades`]: horizon/api-reference/get-trades-by-offer-id
+[`GET /payments`]: horizon/api-reference/list-all-payments
+[`GET /effects`]: horizon/api-reference/list-all-effects
+[`GET /trades`]: horizon/api-reference/get-all-trades
+[`getLatestLedger`]: rpc/api-reference/methods/getLatestLedger
+[`getVersionInfo`]: rpc/api-reference/methods/getVersionInfo
+[`getHealth`]: rpc/api-reference/methods/getHealth
+[`getNetwork`]: rpc/api-reference/methods/getNetwork
+[`getLedgers`]: rpc/api-reference/methods/getLedgers
+[`getTransactions`]: rpc/api-reference/methods/getTransactions
+[`getTransaction`]: rpc/api-reference/methods/getTransaction
+[`getEvents`]: rpc/api-reference/methods/getEvents
+[`sendTransaction`]: rpc/api-reference/methods/sendTransaction
+[`getFeeStats`]: rpc/api-reference/methods/getFeeStats
+[`simulateTransaction`]: rpc/api-reference/methods/simulateTransaction
+[`getLedgerEntries`]: rpc/api-reference/methods/getLedgerEntries

docusaurus.config.ts

@@ -184,6 +184,16 @@ const config: Config = {
               type: 'doc',
               docId: "data/oracles/README",
               label: "Oracles",
+            },
+            {
+              type: 'html',
+              value: '<hr><small>Migration Guides</small>',
+              className: 'subtitle',
+            },
+            {
+              type: 'doc',
+              docId: 'data/migrate-from-horizon-to-rpc/README',
+              label: 'Horizon to RPC'
             }
           ]
         },