Add examples to api documentation

tzarebczan commented

2018-10-11 06:28:40 +02:00

(Migrated from github.com)

To add onto https://github.com/lbryio/lbrycrd/pull/187 and fulfill https://github.com/lbryio/lbry.tech/issues/139, can we generate example calls for each command?

kaykurokawa commented

2018-10-24 19:20:05 +02:00

(Migrated from github.com)

Noting here that there are example calls for commands but it is not being parsed properly

BrannonKing commented

2018-10-25 18:54:57 +02:00

(Migrated from github.com)

@tzarebczan , it's not clear (looking at the parent bug) whether you want command-line examples for this or JSON RPC examples.

Other thoughts: the current "example" sections in the API docs came from the embedded help text in the lbrycrd RPC methods. They are for the command line tool, and they are not consistent in their formatting or in their inclusion on every RPC method. Most of the RPC methods come from pre-existing bitcoin code. I'm hesitant to change that code as it complicates our merge with upstream changes.

@tzarebczan , it's not clear (looking at the parent bug) whether you want command-line examples for this or JSON RPC examples. Other thoughts: the current "example" sections in the API docs came from the embedded help text in the lbrycrd RPC methods. They are for the command line tool, and they are not consistent in their formatting or in their inclusion on every RPC method. Most of the RPC methods come from pre-existing bitcoin code. I'm hesitant to change that code as it complicates our merge with upstream changes.

kauffj commented

2018-10-25 21:30:23 +02:00

(Migrated from github.com)

Providing examples of how to run the commands via cURL or by directly running the CLI tool both make sense.

If I had to pick one, I'd probably say cURL, but this is not a particularly reasoned opinion. Ideally, we could just provide both or even more versions (see Stripe API for an example of how this is done well).

When I looked at the existing docs, it looked like it frequently contained both. Would it be feasible to parse to a structure like this?

    {
        "name": "getblock",
        "namespace": "Blockchain",
        "description": "If verbose is false, returns a string that is serialized, hex-encoded data for block 'hash'. If verbose is true, returns an Object with information about block <hash>.",
        "examples": {
            "cli": "lbrycrd-cli getblock \"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09\",
            "curl": "curl --user myusername --data-binary '{\"jsonrpc\": \"1.0\", \"id\":\"curltest\", \"method\": \"getblock\", \"params\": [\"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09\"] }' -H 'content-type: text/plain;' http://127.0.0.1:9245/"
        },
        "arguments": [
            {
                "name": "hash",
                "type": "string",
                "description": "The block hash",
                "is_required": true
            },
            {
                "name": "verbose",
                "type": "boolean",
                "description": "true for a json object, false for the hex encoded data",
                "is_required": false
            }
        ],
       ...
    },

Providing examples of how to run the commands via `cURL` or by directly running the CLI tool both make sense. If I had to pick one, I'd probably say `cURL`, but this is not a particularly reasoned opinion. Ideally, we could just provide both or even more versions (see [Stripe API](https://stripe.com/docs/api) for an example of how this is done well). When I looked at the existing docs, it looked like it frequently contained both. Would it be feasible to parse to a structure like this? ``` { "name": "getblock", "namespace": "Blockchain", "description": "If verbose is false, returns a string that is serialized, hex-encoded data for block 'hash'. If verbose is true, returns an Object with information about block <hash>.", "examples": { "cli": "lbrycrd-cli getblock \"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09\", "curl": "curl --user myusername --data-binary '{\"jsonrpc\": \"1.0\", \"id\":\"curltest\", \"method\": \"getblock\", \"params\": [\"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09\"] }' -H 'content-type: text/plain;' http://127.0.0.1:9245/" }, "arguments": [ { "name": "hash", "type": "string", "description": "The block hash", "is_required": true }, { "name": "verbose", "type": "boolean", "description": "true for a json object, false for the hex encoded data", "is_required": false } ], ... }, ```

kauffj commented

2018-10-25 21:32:09 +02:00

(Migrated from github.com)

@NetOperatorWibby nothing for you here yet I think, but tagging you so you can follow this ticket.

👍 1

tzarebczan commented

2019-01-21 22:21:16 +01:00

(Migrated from github.com)

@BrannonKing - the SDK team went ahead with the below output format for examples. I think LBRYcrd should be able to do something similar. Lex's plan is to execute these and grab outputs interactively via unit tests.
https://gist.github.com/tzarebczan/1af2e79ba365a006d1b1f0079a3cb03c
https://github.com/lbryio/lbry/pull/1790

@BrannonKing - the SDK team went ahead with the below output format for examples. I think LBRYcrd should be able to do something similar. Lex's plan is to execute these and grab outputs interactively via unit tests. https://gist.github.com/tzarebczan/1af2e79ba365a006d1b1f0079a3cb03c https://github.com/lbryio/lbry/pull/1790

BrannonKing commented

2019-02-12 23:47:10 +01:00

(Migrated from github.com)

I fixed the generator to include an examples field. It will populate it if the existing RPC had examples specified in its CLI help. I've checked in the new generator and the new api_v1.json file, but I have not gone through and added example sections to our claimtrie calls.

BrannonKing commented

2019-03-08 23:25:12 +01:00

(Migrated from github.com)

@NetOperatorWibby , what do I need to do to close this ticket?

tzarebczan commented

2019-03-11 17:13:38 +01:00

(Migrated from github.com)

@BrannonKing lbry.tech reads the json from here: https://github.com/lbryio/lbrycrd/blob/add_api_docs_scripts/contrib/devtools/generated/api_v1.json

(b6b274aa32/app/components/edit-link.js)

Sounds like this link may need to be updated?

@BrannonKing lbry.tech reads the json from here: https://github.com/lbryio/lbrycrd/blob/add_api_docs_scripts/contrib/devtools/generated/api_v1.json (https://github.com/lbryio/lbry.tech/blob/b6b274aa321f44cae057dadae300650cb082cfa9/app/components/edit-link.js) Sounds like this link may need to be updated?

NetOpWibby commented

2019-03-11 17:30:33 +01:00

(Migrated from github.com)

@BrannonKing You may be all set. I'll test it in tech first.

NetOpWibby commented

2019-03-11 17:54:28 +01:00

(Migrated from github.com)

So, looks like JSDelivr has a cached version of the api json file so I had to email them to get it purged. No idea how long that's gonna take. Until they finish their purge tool, we'll have to keep emailing them with purge requests.

Another options is to version the compiled JSON file inside the generated folder.

So, looks like JSDelivr has a cached version of the api json file so I had to email them to get it purged. No idea how long that's gonna take. Until they finish their purge tool, we'll have to keep emailing them with purge requests. Another options is to version the compiled JSON file inside the `generated` folder.

NetOpWibby commented

2019-03-11 17:59:57 +01:00

(Migrated from github.com)

Something weird is happening. Just realized I'm seeing the examples rendered inside of the description.

Sign a message with the private key of an address
Examples:
Unlock the wallet for 30 seconds
> lbrycrd-cli walletpassphrase "mypassphrase" 30

Create the signature
> lbrycrd-cli signmessage "1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XZ" "my message"

Verify the signature
> lbrycrd-cli verifymessage "1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XZ" "signature" "my message"

As json rpc
> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "signmessage", "params": ["1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XZ", "my message"] }' -H 'content-type: text/plain;' http://127.0.0.1:9245/

Something weird is happening. Just realized I'm seeing the examples rendered inside of the description. ``` Sign a message with the private key of an address Examples: Unlock the wallet for 30 seconds > lbrycrd-cli walletpassphrase "mypassphrase" 30 Create the signature > lbrycrd-cli signmessage "1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XZ" "my message" Verify the signature > lbrycrd-cli verifymessage "1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XZ" "signature" "my message" As json rpc > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "signmessage", "params": ["1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XZ", "my message"] }' -H 'content-type: text/plain;' http://127.0.0.1:9245/ ```

BrannonKing commented

2019-03-11 18:23:25 +01:00

(Migrated from github.com)

How do I version it? When I pull up https://github.com/lbryio/lbrycrd/blob/master/contrib/devtools/generated/api_v1.json I see that "Unlock the wallet" is correct.

NetOpWibby commented

2019-03-11 18:30:09 +01:00

(Migrated from github.com)

By "version", I was thinking of doing something like /generated/0.1.0/api.json. However, I don't think that is necessary at this time since I am seeing examples, they are merged with description for some reason.

By "version", I was thinking of doing something like `/generated/0.1.0/api.json`. However, I don't think that is necessary at this time since I _am_ seeing `examples`, they are merged with `description` for some reason.

BrannonKing commented

2019-03-11 18:55:08 +01:00

(Migrated from github.com)

They were merged with description before I changed it a month ago. You're seeing an old version of the api_v1.json file.

NetOpWibby commented

2019-03-11 20:54:07 +01:00

(Migrated from github.com)

https://cdn.jsdelivr.net/gh/lbryio/lbrycrd@master/contrib/devtools/generated/api_v1.json is still showing examples inside the description.

My email got a response from JSDelivr and I ran the curl command to purge twice. Still no change in the link above though. Maybe we just have to wait. I'll come back to this tomorrow.

https://cdn.jsdelivr.net/gh/lbryio/lbrycrd@master/contrib/devtools/generated/api_v1.json is still showing examples inside the description. My email got a response from JSDelivr and I ran the curl command to purge twice. Still no change in the link above though. Maybe we just have to wait. I'll come back to this tomorrow.

BrannonKing commented

2019-03-28 18:52:12 +01:00

(Migrated from github.com)

I have no idea how to update jsdelivr.net or why you might be pulling resources from there. I don't see why that would keep this issue open.

kauffj commented

2019-04-04 00:30:14 +02:00

(Migrated from github.com)

This seems like it's in @NetOperatorWibby's court at this point.

NetOpWibby commented

2019-04-22 21:35:13 +02:00

(Migrated from github.com)

Could the examples match what the SDK API file is doing? https://github.com/lbryio/lbry/blob/master/docs/api.json#L49-L57

"examples": [
  {
    "title": "Get a file",
    "curl": "curl -d'{\"method\": \"get\", \"params\": {\"uri\": \"astream#e3f3e8a3307bcbb15fdaf97bb82340a3a86cf806\"}}' http://localhost:5279/",
    "lbrynet": "lbrynet get astream#e3f3e8a3307bcbb15fdaf97bb82340a3a86cf806",
    "python": "requests.post(\"http://localhost:5279\", json={\"method\": \"get\", \"params\": {\"uri\": \"astream#e3f3e8a3307bcbb15fdaf97bb82340a3a86cf806\"}}).json()",
    "output": "{\n  \"jsonrpc\": \"2.0\",\n  \"result\": {\n    \"blobs_completed\": 1,\n    \"blobs_in_stream\": 1,\n    \"blobs_remaining\": 0,\n    \"channel_claim_id\": \"cc242d221f78975c8011132882ee445b7d9b85cf\",\n    \"channel_name\": \"@channel\",\n    \"claim_id\": \"e3f3e8a3307bcbb15fdaf97bb82340a3a86cf806\",\n    \"claim_name\": \"astream\",\n    \"completed\": false,\n    \"download_directory\": \"/tmp/tmprlkz78lb\",\n    \"download_path\": \"/tmp/tmprlkz78lb/tmpit97x87b\",\n    \"file_name\": \"tmpit97x87b\",\n    \"key\": \"40d70a655061b7981b6d36a84d985fdc\",\n    \"metadata\": {\n      \"source\": {\n        \"hash\": \"b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9\",\n        \"media_type\": \"application/octet-stream\",\n        \"name\": \"tmpit97x87b\",\n        \"sd_hash\": \"a2d66638a51b1621538a92fe3fc4f7a34926dc415652d107b89e28d0bd962074b5bb758adfb3de55053f5cd4dfd97cc7\",\n        \"size\": \"11\"\n      }\n    },\n    \"mime_type\": \"application/octet-stream\",\n    \"nout\": 0,\n    \"outpoint\": \"eb2ff25e7588ea9bc5adeaf80ea66bff8770b5c983754e305b68e5b4199db898:0\",\n    \"points_paid\": 0.0,\n    \"protobuf\": \"01cf859b7d5b44ee82281311805c97781f222d24cce145c0ad7c3c76cd83b5f8044d097413f4198e39a8b4d8012e4055de83212fb94c12834f444142c49a9f46a786b31236b79c7612bdfccae897ef372792b9894e0a7f0a7d0a20b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9120b746d706974393778383762180b22186170706c69636174696f6e2f6f637465742d73747265616d3230a2d66638a51b1621538a92fe3fc4f7a34926dc415652d107b89e28d0bd962074b5bb758adfb3de55053f5cd4dfd97cc7\",\n    \"sd_hash\": \"a2d66638a51b1621538a92fe3fc4f7a34926dc415652d107b89e28d0bd962074b5bb758adfb3de55053f5cd4dfd97cc7\",\n    \"status\": \"running\",\n    \"stopped\": false,\n    \"stream_hash\": \"5bb823532eb1994bbb6c4a7ac44713249768f6e329e6e58a2c1e128ef9a029f850c30757909d0f961f7143a3b7ea439f\",\n    \"stream_name\": \"tmpit97x87b\",\n    \"suggested_file_name\": \"tmpit97x87b\",\n    \"total_bytes\": 16,\n    \"total_bytes_lower_bound\": 0,\n    \"tx\": null,\n    \"txid\": \"eb2ff25e7588ea9bc5adeaf80ea66bff8770b5c983754e305b68e5b4199db898\",\n    \"written_bytes\": 11\n  }\n}"
  }
]

Could the examples match what the SDK API file is doing? https://github.com/lbryio/lbry/blob/master/docs/api.json#L49-L57 ```json "examples": [ { "title": "Get a file", "curl": "curl -d'{\"method\": \"get\", \"params\": {\"uri\": \"astream#e3f3e8a3307bcbb15fdaf97bb82340a3a86cf806\"}}' http://localhost:5279/", "lbrynet": "lbrynet get astream#e3f3e8a3307bcbb15fdaf97bb82340a3a86cf806", "python": "requests.post(\"http://localhost:5279\", json={\"method\": \"get\", \"params\": {\"uri\": \"astream#e3f3e8a3307bcbb15fdaf97bb82340a3a86cf806\"}}).json()", "output": "{\n \"jsonrpc\": \"2.0\",\n \"result\": {\n \"blobs_completed\": 1,\n \"blobs_in_stream\": 1,\n \"blobs_remaining\": 0,\n \"channel_claim_id\": \"cc242d221f78975c8011132882ee445b7d9b85cf\",\n \"channel_name\": \"@channel\",\n \"claim_id\": \"e3f3e8a3307bcbb15fdaf97bb82340a3a86cf806\",\n \"claim_name\": \"astream\",\n \"completed\": false,\n \"download_directory\": \"/tmp/tmprlkz78lb\",\n \"download_path\": \"/tmp/tmprlkz78lb/tmpit97x87b\",\n \"file_name\": \"tmpit97x87b\",\n \"key\": \"40d70a655061b7981b6d36a84d985fdc\",\n \"metadata\": {\n \"source\": {\n \"hash\": \"b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9\",\n \"media_type\": \"application/octet-stream\",\n \"name\": \"tmpit97x87b\",\n \"sd_hash\": \"a2d66638a51b1621538a92fe3fc4f7a34926dc415652d107b89e28d0bd962074b5bb758adfb3de55053f5cd4dfd97cc7\",\n \"size\": \"11\"\n }\n },\n \"mime_type\": \"application/octet-stream\",\n \"nout\": 0,\n \"outpoint\": \"eb2ff25e7588ea9bc5adeaf80ea66bff8770b5c983754e305b68e5b4199db898:0\",\n \"points_paid\": 0.0,\n \"protobuf\": \"01cf859b7d5b44ee82281311805c97781f222d24cce145c0ad7c3c76cd83b5f8044d097413f4198e39a8b4d8012e4055de83212fb94c12834f444142c49a9f46a786b31236b79c7612bdfccae897ef372792b9894e0a7f0a7d0a20b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9120b746d706974393778383762180b22186170706c69636174696f6e2f6f637465742d73747265616d3230a2d66638a51b1621538a92fe3fc4f7a34926dc415652d107b89e28d0bd962074b5bb758adfb3de55053f5cd4dfd97cc7\",\n \"sd_hash\": \"a2d66638a51b1621538a92fe3fc4f7a34926dc415652d107b89e28d0bd962074b5bb758adfb3de55053f5cd4dfd97cc7\",\n \"status\": \"running\",\n \"stopped\": false,\n \"stream_hash\": \"5bb823532eb1994bbb6c4a7ac44713249768f6e329e6e58a2c1e128ef9a029f850c30757909d0f961f7143a3b7ea439f\",\n \"stream_name\": \"tmpit97x87b\",\n \"suggested_file_name\": \"tmpit97x87b\",\n \"total_bytes\": 16,\n \"total_bytes_lower_bound\": 0,\n \"tx\": null,\n \"txid\": \"eb2ff25e7588ea9bc5adeaf80ea66bff8770b5c983754e305b68e5b4199db898\",\n \"written_bytes\": 11\n }\n}" } ] ```

BrannonKing commented

2019-05-10 02:12:29 +02:00

(Migrated from github.com)

Done enough for now.

Add examples to api documentation #219