Skip to content

Commit

Permalink
docs: Add REST endpoints migration guide (#8011)
Browse files Browse the repository at this point in the history 
* Add REST endpoints migration guide

* add bank, distrib, evidence

* Add slashing, mint

* Add staking

* Add query

* Add todo

* Typos

* Add link to interact node

* grammar

* Better wording

* Update docs/migrations/rest.md

Co-authored-by: Robert Zaremba <robert@zaremba.ch>

* Update docs/migrations/rest.md

* Add footnote

Co-authored-by: Robert Zaremba <robert@zaremba.ch>
  • Loading branch information
@amaury1093 @robert-zaremba
amaury1093 and robert-zaremba authored Nov 24, 2020
1 parent 53294f5 commit 13bc504
Show file tree
Hide file tree
Showing 3 changed files with 99 additions and 3 deletions.
7 changes: 6 additions & 1 deletion client/rest/rest.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,17 @@ import (
"github.com/gorilla/mux"
)

// DeprecationURL is the URL for migrating deprecated REST endpoints to newer ones.
// TODO Switch to `/` (not `/master`) once v0.40 docs are deployed.
// https://github.com/cosmos/cosmos-sdk/issues/8019
const DeprecationURL = "https://docs.cosmos.network/master/migrations/rest.html"

// addHTTPDeprecationHeaders is a mux middleware function for adding HTTP
// Deprecation headers to a http handler
func addHTTPDeprecationHeaders(h http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Deprecation", "true")
w.Header().Set("Link", "<https://docs.cosmos.network/v0.40/interfaces/rest.html>; rel=\"deprecation\"")
w.Header().Set("Link", "<"+DeprecationURL+">; rel=\"deprecation\"")
w.Header().Set("Warning", "199 - \"this endpoint is deprecated and may not work as before, see deprecation link for more info\"")
h.ServeHTTP(w, r)
})
Expand Down
89 changes: 89 additions & 0 deletions docs/migrations/rest.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# REST Endpoints Migration

Migrate your REST endpoints to the Stargate ones. {synopsis}

## Deprecation of Legacy REST Endpoints

The Cosmos SDK versions v0.39 and earlier provided REST endpoints to query the state and broadcast transactions. These endpoints are kept in Cosmos SDK v0.40 (Stargate), but they are marked as deprecated, and will be removed in v0.41. We therefore call these endpoints legacy REST endpoints.

Some important information concerning all legacy REST endpoints:

- Most of these endpoints are backwards-comptatible. All breaking changes are described in the next section.
- In particular, these endpoints still output Amino JSON. Cosmos v0.40 introduced Protobuf as the default encoding library throughout the codebase, but legacy REST endpoints are one of the few places where the encoding is hardcoded to Amino. For more information about Protobuf and Amino, please read our [encoding guide](../core/encoding.md).
- All legacy REST endpoints include a [HTTP deprecation header](https://tools.ietf.org/id/draft-dalal-deprecation-header-01.html) which links to this document.

## Breaking Changes in Legacy REST Endpoints

| Legacy REST Endpoint | Description | Breaking Change |
| ------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET /txs/{hash}` | Query tx by hash | Endpoint will error when trying to output transactions that don't support Amino serialization (e.g. IBC txs)<sup>1</sup>. |
| `GET /txs` | Query tx by events | Endpoint will error when trying to output transactions that don't support Amino serialization (e.g. IBC txs)<sup>1</sup>. |
| `GET /staking/validators` | Get all validators | BondStatus is now a protobuf enum instead of an int32, and JSON serialized using its protobuf name, so expect query parameters like `?status=BOND_STATUS_{BONDED,UNBONDED,UNBONDING}` as opposed to `?status={bonded,unbonded,unbonding}`. |

<sup>1</sup>: Transactions that don't support Amino serialization are the ones that contain one or more `Msg`s that are not registered with the Amino codec. Currently in the SDK, only IBC `Msg`s fall into this case.

## Migrating to New REST Endpoints

Thanks to the Protocol Buffers migration in v0.40 we are able to take advantage of a vast number of gRPC tools and solutions. For most of the legacy REST endpoints, Cosmos SDK v0.40 provides new REST endpoints generated from [gRPC `Query` services](../building-modules/query-services.md) using [grpc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/). We usually call them _gGPC-gateway REST endpoints_.

Some modules expose legacy `POST` endpoints to generate unsigned transactions for their `Msg`s. These `POST` endpoints have been removed. We recommend to use [service `Msg`s](../building-modules/msg-services.md) directly, and use Protobuf to do client-side transaction generation. A guide can be found [here (TODO)](https://github.com/cosmos/cosmos-sdk/issues/7657).

| Legacy REST Endpoint | Description | New gGPC-gateway REST Endpoint |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `GET /txs/{hash}` | Query tx by hash | `GET /cosmos/tx/v1beta1/tx/{hash}` |
| `GET /txs` | Query tx by events | `GET /cosmos/tx/v1beta1/txs` |
| `POST /txs` | Broadcast tx | `POST /cosmos/tx/v1beta1/txs` |
| `POST /txs/encode` | Encodes an Amino JSON tx to an Amino binary tx | N/A, use Protobuf directly |
| `POST /txs/decode` | Decodes an Amino binary tx into an Amino JSON tx | N/A, use Protobuf directly |
| `POST /bank/*` | Create unsigned `Msg`s for bank tx | N/A, use Protobuf directly |
| `GET /bank/balances/{address}` | Get the balance of an address | `GET /cosmos/bank/v1beta1/balances/{address}/{denom}` |
| `GET /bank/total` | Get the total supply of all coins | `GET /cosmos/bank/v1beta1/supply` |
| `GET /bank/total/{denom}` | Get the total supply of one coin | `GET /cosmos/bank/v1beta1/supply/{denom}` |
| `POST /distribution/delegators/{delegatorAddr}/rewards` | Withdraw all delegator rewards | N/A, use Protobuf directly |
| `POST /distribution/*` | Create unsigned `Msg`s for distribution | N/A, use Protobuf directly |
| `GET /distribution/delegators/{delegatorAddr}/rewards` | Get the total rewards balance from all delegations | `GET /cosmos/distribution/v1beta1/v1beta1/delegators/{delegator_address}/rewards` |
| `GET /distribution/delegators/{delegatorAddr}/rewards/{validatorAddr}` | Query a delegation reward | `GET /cosmos/distribution/v1beta1/delegators/{delegatorAddr}/rewards/{validatorAddr}` |
| `GET /distribution/delegators/{delegatorAddr}/withdraw_address` | Get the rewards withdrawal address | `GET /cosmos/distribution/v1beta1/delegators/{delegatorAddr}/withdraw_address` |
| `GET /distribution/validators/{validatorAddr}` | Validator distribution information | `GET /cosmos/distribution/v1beta1/validators/{validatorAddr}` |
| `GET /distribution/validators/{validatorAddr}/rewards` | Commission and self-delegation rewards of a single a validator | `GET /cosmos/distribution/v1beta1/validators/{validatorAddr}/rewards` |
| `GET /distribution/validators/{validatorAddr}/outstanding_rewards` | Outstanding rewards of a single validator | `GET /cosmos/distribution/v1beta1/validators/{validatorAddr}/outstanding_rewards` |
| `GET /distribution/parameters` | Get the current distribution parameter values | `GET /cosmos/distribution/v1beta1/params` |
| `GET /distribution/community_pool` | Get the amount held in the community pool | `GET /cosmos/distribution/v1beta1/community_pool` |
| `GET /evidence/{evidence-hash}` | Get evidence by hash | `GET /cosmos/evidence/v1beta1/evidence/{evidence_hash}` |
| `GET /evidence` | Get all evidence | `GET /cosmos/evidence/v1beta1/evidence` |
| `POST /gov/*` | Create unsigned `Msg`s for gov | N/A, use Protobuf directly |
| `GET /gov/parameters/{type}` | Get government parameters | `GET /cosmos/gov/v1beta1/params/{type}` |
| `GET /gov/proposals` | Get all proposals | `GET /cosmos/gov/v1beta1/proposals` |
| `GET /gov/proposals/{proposal-id}` | Get proposal by id | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}` |
| `GET /gov/proposals/{proposal-id}/proposer` | Get proposer of a proposal | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}` (Get proposer from `Proposal` struct) |
| `GET /gov/proposals/{proposal-id}/deposits` | Get deposits of a proposal | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}/deposits` |
| `GET /gov/proposals/{proposal-id}/deposits/{depositor}` | Get depositor a of deposit | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}/deposits/{depositor}` |
| `GET /gov/proposals/{proposal-id}/tally` | Get tally of a proposal | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}/tally` |
| `GET /gov/proposals/{proposal-id}/votes` | Get votes of a proposal | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}/votes` |
| `GET /gov/proposals/{proposal-id}/votes/{vote}` | Get a particular vote | `GET /cosmos/gov/v1beta1/proposals/{proposal-id}/votes/{vote}` |
| `GET /minting/parameters` | Get parameters for minting | `GET /cosmos/minting/v1beta1/params` |
| `GET /minting/inflation` | Get minting inflation | `GET /cosmos/minting/v1beta1/inflation` |
| `GET /minting/annual-provisions` | Get minting annual provisions | `GET /cosmos/minting/v1beta1/annual_provisions` |
| `POST /slashing/*` | Create unsigned `Msg`s for slashing | N/A, use Protobuf directly |
| `GET /slashing/validators/{validatorPubKey}/signing_info` | Get validator signing info | `GET /cosmos/slashing/v1beta1/signing_infos/{cons_address}` (Use consensus address instead of pubkey) |
| `GET /slashing/signing_infos` | Get all signing infos | `GET /cosmos/slashing/v1beta1/signing_infos` |
| `GET /slashing/parameters` | Get slashing parameters | `GET /cosmos/slashing/v1beta1/params` |
| `POST /staking/*` | Create unsigned `Msg`s for staking | N/A, use Protobuf directly |
| `GET /staking/delegators/{delegatorAddr}/delegations` | Get all delegations from a delegator | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/delegations` |
| `GET /staking/delegators/{delegatorAddr}/unbonding_delegations` | Get all unbonding delegations from a delegator | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/unbonding_delegations` |
| `GET /staking/delegators/{delegatorAddr}/txs` | Get all staking txs (i.e msgs) from a delegator | Removed |
| `GET /staking/delegators/{delegatorAddr}/validators` | Query all validators that a delegator is bonded to | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/validators` |
| `GET /staking/delegators/{delegatorAddr}/validators/{validatorAddr}` | Query a validator that a delegator is bonded to | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/validators/{validatorAddr}` |
| `GET /staking/delegators/{delegatorAddr}/delegations/{validatorAddr}` | Query a delegation between a delegator and a validator | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/delegations/{validatorAddr}` |
| `GET /staking/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr}` | Query all unbonding delegations between a delegator and a validator | `GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr}` |
| `GET /staking/redelegations` | Query redelegations | `GET /cosmos/staking/v1beta1/v1beta1/delegators/{delegator_addr}/redelegations` |
| `GET /staking/validators` | Get all validators | `GET /cosmos/staking/v1beta1/validators` |
| `GET /staking/validators/{validatorAddr}` | Get a single validator info | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}` |
| `GET /staking/validators/{validatorAddr}/delegations` | Get all delegations to a validator | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}/delegations` |
| `GET /staking/validators/{validatorAddr}/unbonding_delegations` | Get all unbonding delegations from a validator | `GET /cosmos/staking/v1beta1/validators/{validatorAddr}/unbonding_delegations` |
| `GET /staking/historical_info/{height}` | Get HistoricalInfo at a given height | `GET /cosmos/staking/v1beta1/historical_info/{height}` |
| `GET /staking/pool` | Get the current state of the staking pool | `GET /cosmos/staking/v1beta1/pool` |
| `GET /staking/parameters` | Get the current staking parameter values | `GET /cosmos/staking/v1beta1/params` |
| `POST /upgrade/*` | Create unsigned `Msg`s for upgrade | N/A, use Protobuf directly |
| `GET /upgrade/current` | Get the current plan | `GET /cosmos/upgrade/v1beta1/current_plan` |
| `GET /upgrade/applied_plan/{name}` | Get a previously applied plan | `GET /cosmos/upgrade/v1beta1/applied/{name}` |
Loading

0 comments on commit 13bc504

Please sign in to comment.