Data API v2.2 (#193)

* data api 2.2 - ported docs from upstream (some edits)

* Data API v2.2 - some cleanup, API tool methods (incomplete)

* Data API v2.2 - more cleanup (draft done)

* Data API v2.2 - minor cleanup

* Data API tool - fix 'a transactions' typo

assets/js/apitool-methods-data_v2.js

@@ -8,15 +8,17 @@ var KRW_TRADER_ADDRESS = "rsyDrDi9Emy6vPU78qdxovmNpmj5Qh4NKw";
 var JPY_TRADER_ADDRESS = "rK5j9n8baXfL4gzUoZsfxBvvsv97P5swaV";
 var DEFAULT_HASH = "9D591B18EDDD34F0B6CF4223A2940AEA2C3CC778925BABF289E0011CD8FA056E";
 var DEFAULT_LEDGER = "3170DA37CE2B7F045F889594CBC323D88686D2E90E8FFD2BBCD9BAD12E416DB5";
+var VALIDATOR_PUBKEY = "n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7";
+var LEDGER_WITH_VALIDATIONS = "A10E9E338BA365D2B768814EC8B0A9A2D8322C0040735E20624AF711C5A593E7";
 
 // general methods -----------------------------------//
 
-Request("GENERAL METHODS");
+Request("LEDGER CONTENTS");
 
 Request('Get Ledger', {
     method: GET,
     path: "/v2/ledgers/{:ledger_identifier}?{:query_params}",
-    description: "Retrieve a ledger by its sequence number or identifying hash.",
+    description: "Get a ledger by its sequence number or identifying hash.",
     link: "#get-ledger",
     params: {
         "{:ledger_identifier}": DEFAULT_LEDGER,
@@ -27,7 +29,7 @@ Request('Get Ledger', {
 Request('Get Transaction', {
     method: GET,
     path: "/v2/transactions/{:hash}?{:query_params}",
-    description: "Retrieve a transactions by its identifying hash.",
+    description: "Get a transaction by its identifying hash.",
     link: "#get-transaction",
     params: {
         "{:hash}": DEFAULT_HASH,
@@ -48,7 +50,7 @@ Request('Get Transactions', {
 Request('Get Payments', {
     method: GET,
     path: "/v2/payments/{:currency}?{:query_params}",
-    description: "Retrieve Payments over time, where Payments are defined as Payment-type transactions where the sender of the transaction is not also the destination. ",
+    description: "Get Payments over time, where Payments are defined as Payment-type transactions where the sender of the transaction is not also the destination. ",
     link: "#get-payments",
     params: {
         "{:currency}": "BTC+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
@@ -60,7 +62,7 @@ Request('Get Payments', {
 Request('Get Exchanges', {
     method: GET,
     path: "/v2/exchanges/{:base}/{:counter}?{:query_params}",
-    description: "Retrieve exchanges for a currency pair over time.",
+    description: "Get exchanges for a currency pair over time.",
     link: "#get-exchanges",
     params: {
         "{:base}": "USD+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
@@ -72,7 +74,7 @@ Request('Get Exchanges', {
 Request('Get Exchange Rates', {
     method: GET,
     path: "/v2/exchange_rates/{:base}/{:counter}?{:query_params}",
-    description: "Retrieve an exchange rate for a given currency pair at a specific time.",
+    description: "Get an exchange rate for a given currency pair at a specific time.",
     link: "#get-exchange-rates",
     params: {
         "{:base}": "USD+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
@@ -94,7 +96,7 @@ Request('Normalize', {
 Request('Get Daily Reports', {
     method: GET,
     path: "/v2/reports/{:date}?{:query_params}",
-    description: "Retrieve an aggregated summary of payments per account for one day.",
+    description: "Get an aggregated summary of payments per account for one day.",
     link: "#get-daily-reports",
     params: {
         "{:date}": "2015-08-19T00:00:00Z",
@@ -105,7 +107,7 @@ Request('Get Daily Reports', {
 Request('Get Stats', {
     method: GET,
     path: "/v2/stats/?{:query_params}",
-    description: "Retrieve an aggregated summary of payments per account for one day.",
+    description: "Get an aggregated summary of payments per account for one day.",
     link: "#get-daily-summary",
     params: {
         "{:query_params}": "start=2015-08-30&end=2015-08-31&interval=day&family=metric&metrics=accounts_created,exchanges_count,ledger_count,payments_count"
@@ -165,13 +167,25 @@ Request('Get Issued Value', {
     }
 });
 
+
+Request('Get XRP Distribution', {
+    method: GET,
+    path: "/v2/network/xrp_distribution?{:query_params}",
+    description: "Get info on how much XRP is available and how much has been distributed outside of Ripple (the company).",
+    link: "#get-xrp-distribution",
+    params: {
+        "{:query_params}": "limit=3&descending=true"
+    }
+});
+
 Request('Get Top Currencies', {
     method: GET,
-    path: "/v2/network/top_currencies/{:date}",
+    path: "/v2/network/top_currencies/{:date}?{:query_params}",
     description: "Get most used currencies for a given date.",
     link: "#get-top-currencies",
     params: {
-        "{:date}": "2016-04-14"
+        "{:date}": "2016-04-14",
+        "{:query_params}": "limit=2"
     }
 });
 
@@ -185,28 +199,9 @@ Request('Get Top Markets', {
     }
 });
 
-Request('Get All Gateways', {
-    method: GET,
-    path: "/v2/gateways",
-    description: "Get information about known gateways.",
-    link: "#get-all-gateways",
-    params: {}
-});
-
-Request('Get Gateway', {
-    method: GET,
-    path: "/v2/gateways/{:gateway}",
-    description: "Get information about a specific known gateway.",
-    link: "#get-gateway",
-    params: {
-        "{:gateway}": "Gatehub"
-    }
-});
-
-
 // account methods -----------------------------------//
 
-Request("ACCOUNT METHODS");
+Request("ACCOUNTS");
 
 Request('Get Account', {
     method: GET,
@@ -231,7 +226,7 @@ Request('Get Accounts', {
 Request('Get Account Balances', {
     method: GET,
     path: "/v2/accounts/{:address}/balances?{:query_params}",
-    description: "Retrieve a given account's balances at a given time.",
+    description: "Get a given account's balances at a given time.",
     link: "#get-account-balances",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
@@ -255,7 +250,7 @@ Request('Get Account Orders', {
 Request('Get Account Transaction History', {
     method: GET,
     path: "/v2/accounts/{:address}/transactions?{:query_params}",
-    description: "Retrieve transactions that affected the given account.",
+    description: "Get transactions that affected the given account.",
     link: "#get-account-transaction-history",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
@@ -266,7 +261,7 @@ Request('Get Account Transaction History', {
 Request('Get Transaction By Account and Sequence', {
     method: GET,
     path: "/v2/accounts/{:address}/transactions/{:sequence}?{:query_params}",
-    description: "Retrieve a transaction using the sending account and sequence number.",
+    description: "Get a transaction using the sending account and sequence number.",
     link: "#get-transaction-by-account-and-sequence",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
@@ -278,7 +273,7 @@ Request('Get Transaction By Account and Sequence', {
 Request('Get Account Payments', {
     method: GET,
     path: "/v2/accounts/{:address}/payments?{:query_params}",
-    description: "Retrieve payments to and from a given account.",
+    description: "Get payments to and from a given account.",
     link: "#get-account-payments",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
@@ -289,7 +284,7 @@ Request('Get Account Payments', {
 Request('Get Account Exchanges - All', {
     method: GET,
     path: "/v2/accounts/{:address}/exchanges?{:query_params}",
-    description: "Retrieve all currency changes in which a given account participated.",
+    description: "Get all currency changes in which a given account participated.",
     link: "#get-account-exchanges",
     params: {
         "{:address}": KRW_TRADER_ADDRESS,
@@ -300,7 +295,7 @@ Request('Get Account Exchanges - All', {
 Request('Get Account Exchanges - Single Currency Pair', {
     method: GET,
     path: "/v2/accounts/{:address}/exchanges/{:base}/{:counter}?{:query_params}",
-    description: "Retrieve exchanges of a specific currency pair in which a given account participated.",
+    description: "Get exchanges of a specific currency pair in which a given account participated.",
     link: "#get-account-exchanges",
     params: {
         "{:address}": KRW_TRADER_ADDRESS,
@@ -313,7 +308,7 @@ Request('Get Account Exchanges - Single Currency Pair', {
 Request('Get Account Balance Changes', {
     method: GET,
     path: "/v2/accounts/{:address}/balance_changes?{:query_params}",
-    description: "Retrieve detailed account of all changes to an account's balance.",
+    description: "Get detailed account of all changes to an account's balance.",
     link: "#get-account-balance-changes",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
@@ -324,7 +319,7 @@ Request('Get Account Balance Changes', {
 Request('Get Account Reports By Day', {
     method: GET,
     path: "/v2/accounts/{:address}/reports/{:date}?{:query_params}",
-    description: "Retrieve summary of account activity for a given account on a certain day.",
+    description: "Get summary of account activity for a given account on a certain day.",
     link: "#get-account-reports",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
@@ -336,7 +331,7 @@ Request('Get Account Reports By Day', {
 Request('Get Account Reports Range', {
     method: GET,
     path: "/v2/accounts/{:address}/reports?{:query_params}",
-    description: "Retrieve multiple daily summaries of account activity.",
+    description: "Get multiple daily summaries of account activity.",
     link: "#get-account-reports",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
@@ -347,7 +342,7 @@ Request('Get Account Reports Range', {
 Request('Get Account Transaction Stats', {
     method: GET,
     path: "/v2/accounts/{:address}/stats/transactions?{:query_params}",
-    description: "Retrieve daily summaries of transaction activity for an account.",
+    description: "Get daily summaries of transaction activity for an account.",
     link: "#get-account-transaction-stats",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
@@ -358,12 +353,218 @@ Request('Get Account Transaction Stats', {
 Request('Get Account Value Stats', {
     method: GET,
     path: "/v2/accounts/{:address}/stats/value?{:query_params}",
-    description: "Retrieve daily summaries of the currency held by an account.",
+    description: "Get daily summaries of the currency held by an account.",
     link: "#get-account-value-stats",
     params: {
         "{:address}": DEFAULT_ADDRESS_1,
         "{:query_params}": "limit=2&descending=true"
     }
 })
+//-------------- Validation Network 00----------------//
+
+Request("VALIDATION NETWORK");
+
+
+Request('Get Transaction Costs', {
+    method: GET,
+    path: "/v2/network/fees?{:query_params}",
+    description: "Get stats on the transaction cost.",
+    link: "#get-network-fees",
+    params: {
+        "{:query_params}": "interval=day&limit=3&descending=true"
+    }
+});
+
+Request('Get Ledger Validations', {
+    method: GET,
+    path: "/v2/ledgers/{:ledger_hash}/validations?{:query_params}",
+    description: "Get data on validations for a specific ledger hash.",
+    link: "#get-ledger-validations",
+    params: {
+        "{:ledger_hash}": LEDGER_WITH_VALIDATIONS,
+        "{:query_params}": "limit=2"
+    }
+});
+
+Request('Get Ledger Validation', {
+    method: GET,
+    path: "/v2/ledgers/{:ledger_hash}/validations/{:validation_public_key}",
+    description: "Get data on validation for a specific ledger hash by a specific validator.",
+    link: "#get-ledger-validation",
+    params: {
+        "{:ledger_hash}": LEDGER_WITH_VALIDATIONS,
+        "{:validation_public_key}": VALIDATOR_PUBKEY
+    }
+});
+
+Request('Get Topology', {
+    method: GET,
+    path: "/v2/network/topology?{:query_params}",
+    description: "Get topology of servers running the Ripple peer-to-peer network.",
+    link: "#get-topology",
+    params: {
+        "{:query_params}": "verbose=true"
+    }
+});
+
+Request('Get Topology Nodes', {
+    method: GET,
+    path: "/v2/network/topology/nodes?{:query_params}",
+    description: "Get data on servers running the Ripple peer-to-peer network.",
+    link: "#get-topology-nodes",
+    params: {
+        "{:query_params}": "verbose=true"
+    }
+});
+
+Request('Get Topology Node', {
+    method: GET,
+    path: "/v2/network/topology/nodes/{:pubkey}",
+    description: "Get data on servers running the Ripple peer-to-peer network.",
+    link: "#get-topology-nodes",
+    params: {
+        "{:pubkey}": "n94h5KNspwUGLaGcdHGxruYNmExWHjPkLcMvwsNrivR9czRp6Lor"
+    }
+});
+
+Request('Get Topology Links', {
+    method: GET,
+    path: "/v2/network/topology/links?{:query_params}",
+    description: "Get links in the topology of servers running the Ripple peer-to-peer network.",
+    link: "#get-topology-links",
+    params: {
+        "{:query_params}": "verbose=true"
+    }
+});
+
+Request('Get Validations', {
+    method: GET,
+    path: "/v2/network/validations?{:query_params}",
+    description: "Get validation votes.",
+    link: "#get-validations",
+    params: {
+        "{:query_params}": "limit=3&descending=true"
+    }
+});
+
+Request('Get Validator', {
+    method: GET,
+    path: "/v2/network/validators/{:validation_public_key}?{:query_params}",
+    description: "Get details of a single validator by validation public key.",
+    link: "#get-validator",
+    params: {
+        "{:validation_public_key}": VALIDATOR_PUBKEY,
+        "{:query_params}": "verbose=true"
+    }
+});
+
+Request('Get Validators', {
+    method: GET,
+    path: "/v2/network/validators?{:query_params}",
+    description: "Get details of known validators.",
+    link: "#get-validators",
+    params: {
+        "{:validation_public_key}": VALIDATOR_PUBKEY,
+        "{:query_params}": "format=json"
+    }
+});
+
+Request('Get Validator Validations', {
+    method: GET,
+    path: "/v2/network/validators/{:validation_public_key}/validations?{:query_params}",
+    description: "Get validation votes from a single validator.",
+    link: "#get-validator-validations",
+    params: {
+        "{:validation_public_key}": VALIDATOR_PUBKEY,
+        "{:query_params}": "limit=3"
+    }
+});
+
+Request('Get Single Validator Reports', {
+    method: GET,
+    path: "/v2/network/validators/{:validation_public_key}/reports?{:query_params}",
+    description: "Get validation vote stats for a single validator over time.",
+    link: "#get-single-validator-reports",
+    params: {
+        "{:validation_public_key}": VALIDATOR_PUBKEY,
+        "{:query_params}": "format=json"
+    }
+});
+
+Request('Get Daily Validator Reports', {
+    method: GET,
+    path: "/v2/network/validator_reports?{:query_params}",
+    description: "Get validation vote stats for all validators for a single day.",
+    link: "#get-single-validator-reports",
+    params: {
+        "{:query_params}": "format=json"
+    }
+});
+
+//-------------- Gateway Information -----------------//
+
+Request("GATEWAY INFORMATION");
+
+Request('Get All Gateways', {
+    method: GET,
+    path: "/v2/gateways",
+    description: "Get information about known gateways.",
+    link: "#get-all-gateways",
+    params: {}
+});
+
+Request('Get Gateway', {
+    method: GET,
+    path: "/v2/gateways/{:gateway}",
+    description: "Get information about a specific known gateway.",
+    link: "#get-gateway",
+    params: {
+        "{:gateway}": "Gatehub"
+    }
+});
+
+//-------------- Health Checks -----------------------//
+
+Request("HEALTH CHECKS");
+
+Request('API Health Check', {
+    method: GET,
+    path: "/v2/health/api?{:query_params}",
+    description: "Check the health of the API service.",
+    link: "#health-check-api",
+    params: {
+        "{:query_params}": "verbose=true"
+    }
+});
+
+Request('Importer Health Check', {
+    method: GET,
+    path: "/v2/health/importer?{:query_params}",
+    description: "Check the health of the Ledger Importer service.",
+    link: "#health-check-ledger-importer",
+    params: {
+        "{:query_params}": "verbose=true"
+    }
+});
+
+Request('Nodes ETL Health Check', {
+    method: GET,
+    path: "/v2/health/nodes_etl?{:query_params}",
+    description: "Check the health of the Extract, Transform, Load service for network topology data.",
+    link: "#health-check-nodes-etl",
+    params: {
+        "{:query_params}": "verbose=true"
+    }
+});
+
+Request('Validations ETL Health Check', {
+    method: GET,
+    path: "/v2/health/nodes_etl?{:query_params}",
+    description: "Check the health of the Extract, Transform, Load service for ledger validations.",
+    link: "#health-check-validations-etl",
+    params: {
+        "{:query_params}": "verbose=true"
+    }
+});
 
 //---------- End req. List ---------------------------//

content/data_types/public_key.md

@@ -0,0 +1,13 @@
+The Ripple Consensus Ledger (RCL) uses public keys to verify cryptographic signatures in several places:
+
+* To authorize transactions, a public key is attached to the transaction. The public key must be mathematically associated with the sending Ripple address or the sender's regular key address.
+* To secure peer-to-peer communications between `rippled` servers. This uses a "node public key" that the server generates randomly when it starts with an empty database.
+* To sign validation votes as part of the consensus process. This uses a "validator public key" that the server operator [defines in the config file](tutorial-rippled-setup.html#validator-setup).
+
+Validator public keys and node public keys use the exact same format.
+
+Public keys can be represented in hexadecimal or in base-58. In hexadecimal, all three types of public keys are 33 bytes (66 characters) long.
+
+In base-58 format, validator public keys and node public keys always start with the character `n`, commonly followed by the character `9`. A validator public key in base-58 format can be up to 53 characters long. Example node public key: `n9Mxf6qD4J55XeLSCEpqaePW4GjoCR5U1ZeGZGJUCNe3bQa4yQbG`.
+
+Ripple addresses are mathematically associated with a public key. This public key is rarely encoded in base-58, but when it is, it starts with the character `a`.