From a42795072a5b8d56f538c32427344225f2d2b282 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Fri, 9 Nov 2018 11:49:26 -0800 Subject: [PATCH] Data API doc revs per review --- content/references/data-api.md | 71 ++++++++++++++++++++++++++++------ 1 file changed, 59 insertions(+), 12 deletions(-) diff --git a/content/references/data-api.md b/content/references/data-api.md index cb7171de65..2cf083c8d5 100644 --- a/content/references/data-api.md +++ b/content/references/data-api.md @@ -26,6 +26,7 @@ The Ripple Data API v2 replaces the Historical Database v1 and the [Charts API]( [v2.3.0]: https://github.com/ripple/rippled-historical-database/releases/tag/v2.3.0 [v2.3.2]: https://github.com/ripple/rippled-historical-database/releases/tag/v2.3.2 [v2.3.5]: https://github.com/ripple/rippled-historical-database/releases/tag/v2.3.5 +[v2.3.7]: https://github.com/ripple/rippled-historical-database/releases/tag/v2.3.7 [v2.4.0]: https://github.com/ripple/rippled-historical-database/releases/tag/v2.4.0 @@ -2656,6 +2657,8 @@ GET /v2/network/validators/{pubkey} +[Try it! >](data-api-v2-tool.html#get-validator) + This method requires the following URL parameters: | Field | Value | Description | @@ -2682,7 +2685,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `current_index` | Number | Ledger index of most recently validated ledger. | | `partial` | Bool | True if the most recent validation was a partial one. | | `agreement_1h` | Agreement Object | Object containing agreement stats for the most recent hour. | -| `aggreement_24h` | Agreement Object | Object containing agreement stats for the most recent 24 hour period. | +| `agreement_24h` | Agreement Object | Object containing agreement stats for the most recent 24 hour period. | #### Agreement Objects @@ -2698,7 +2701,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the Request: ``` -GET /v2/network/validators/n949f75evCHwgyP4fPVgaHqNHxUVN15PsJEZ3B3HnXPcPjcZAoy7 +GET /v2/network/validators/nHBidG3pZK11zQD6kpNDoAhDxH6WLGui6ZxSbUx7LSqLHsgzMPec ``` Response: @@ -2767,6 +2770,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `validators` | Array of [Validator Objects][] | List of validators active in the last 24 hours. | #### Validator Objects +[Validator Objects]: #validator-objects | Field | Value | Description | |:------------------------|:--------------------------------|:-----------------| @@ -2777,7 +2781,7 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `current_index` | Number | Ledger index of most recently validated ledger. | | `partial` | Bool | True if the most recent validation was a partial one. | | `agreement_1h` | Agreement Object | Object containing agreement stats for the most recent hour. | -| `aggreement_24h` | Agreement Object | Object containing agreement stats for the most recent 24 hour period. | +| `agreement_24h` | Agreement Object | Object containing agreement stats for the most recent 24 hour period. | #### Agreement Objects @@ -2823,7 +2827,29 @@ Response: }, "partial": false, "unl": true - } + }, + { + "validation_public_key": "nHUStq4qu3NXaL6T42wbtpR8mare8gWMVYrUzek227c6QeUn6QGN", + "domain": "blockchain.korea.ac.kr", + "chain": "main", + "current_index": 42860792, + "agreement_1h": { + "missed": 0, + "total": 995, + "score": "1.0000", + "incomplete": false + }, + "agreement_24h": { + "missed": 0, + "total": 23478, + "score": "1.0000", + "incomplete": false + }, + "partial": false, + "unl": true + }, + + ... ] } ``` @@ -2833,7 +2859,7 @@ Response: ## Get Validator Manifests [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getManifests.js "Source") -Retrieve manifests signed by a specified validator, used to designate ephemeral key to sign proposals and validations. _(New in [v2.3.7][])_ +Retrieve manifests signed by a specified validator. (Manifests, also called _subkey authorizations_, designate the ephemeral key a validator uses to sign proposals and validations.) _(New in [v2.3.7][])_ **Note:** The Data API does not have a comprehensive record of all manifests. The response only includes data that the Data API has recorded. @@ -2849,6 +2875,8 @@ GET /v2/network/validators/{pubkey}/manifests +[Try it! >](data-api-v2-tool.html#get-validator-manifests) + This method requires the following URL parameters: | Field | Value | Description | @@ -2874,6 +2902,21 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | `marker` | String | (May be omitted) [Pagination](#pagination) marker. | | `manifests` | Array of [Manifest Objects][] | The requested manifests. | +#### Manifest Objects +[Manifest Objects]: #manifest-objects + +Each manifest object contains the following: + +| Field | Value | Description | +|:-----------------------|:--------------------------------|:------------------| +| `count` | Number | How many times the Data API has seen this manifest. Lower numbers mean the manifest is more recent. | +| `ephemeral_public_key` | String - Base-58 [Public Key][] | The ephemeral public key for this validator encoded in this manifest. | +| `first_datetime` | String - [Timestamp][] | The time the Data API first saw this manifest. | +| `last_datetime` | String - [Timestamp][] | The time the Data API most recently saw this manifest. | +| `master_public_key` | String - Base-58 [Public Key][] | The master public key that identifies this validator. | +| `master_signature` | String - Hexadecimal | Signature from the validator master key authorizing this manifest. | +| `sequence` | Number | The sequence number of this manifest. Higher-sequence manifests replace older manifests, rotating the ephemeral keys. | +| `signature` | String - Hexadecimal | Signature from ephemeral key authorized by this manifest. | #### Example @@ -2961,10 +3004,13 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the | Field | Value | Description | |:-------------|:-----------------------------------------|:-------------------| | `result` | String | The value `success` indicates that the body represents a successful response. | -| `count` | Integer | Number of validators returned. | -| `reports` | Array of Single Validator Report Objects | Daily reports of this validator's validation votes. | +| `count` | Integer | Number of validator daily reports returned. | +| `reports` | Array of [Single Validator Report Objects][] | Daily reports of each validator's performance on that day. | -Each member in the `reports` array is a Single Validator Report Object with data on that validator's performance on that day. Each has the following fields: +##### Single Validator Report Objects +[Single Validator Report Objects]: #single-validator-report-objects + +Each Single Validator Report Object describes a validator's performance on a given day and has the following fields: | Field | Value | Description | |:---------------------|:--------------------------------|:-----------------------------| @@ -3020,7 +3066,7 @@ Response: ## Get Daily Validator Reports [[Source]
](https://github.com/ripple/rippled-historical-database/blob/develop/api/routes/network/getValidatorReports.js "Source") -Get a validation vote stats and validator information for all known validators in a 24-hour period. +Get validation vote stats and validator information for all known validators in a 24-hour period. #### Request Format @@ -3051,11 +3097,12 @@ A successful response uses the HTTP code **200 OK** and has a JSON body with the |:----------|:----------------------------------------|:-----------------------| | `result` | String | The value `success` indicates that the body represents a successful response. | | `count` | Integer | Number of reports returned. | -| `reports` | Array of Daily Validator Report Objects | Summaries of activity for each validator active during this time period. | +| `reports` | Array of [Daily Validator Report Objects][] | Daily summaries of validator performance for each validator active during this time period. | -Daily Validator Report Object fields: +#### Daily Validator Report Objects +[Daily Validator Report Objects]: #daily-validator-report-objects -Each member in the `reports` array is a Single Validator Report Object with data on that validator's performance on that day. Each has the following fields: +Each member in the `reports` array describes one validator's performance on that day and has the following fields: | Field | Value | Description | |:---------------------|:--------------------------------|:-----------------------------|