Browse Source

update api doc (see #75)

umbrel
kenshin-samourai 5 years ago
parent
commit
b5dd9673c1
  1. 9
      doc/POST_auth_login.md
  2. 9
      doc/POST_auth_refresh.md
  3. 1
      doc/POST_pushtx.md
  4. 3
      doc/POST_pushtx_schedule.md
  5. 11
      doc/POST_xpub.md
  6. 9
      doc/POST_xpub_lock.md

9
doc/POST_auth_login.md

@ -2,7 +2,7 @@
Authenticate to the backend by providing the API key expected by the server. If authentication succeeds, the endpoint returns a json embedding an access token and a refresh token (JSON Web Tokens). The access token must be passed as an argument or in the `Authorization` HTTP header for all later calls to the backend (account & pushtx REST API + websockets). The refresh token must be passed as an argument or in the `Authorization` HTTP header for later calls to /auth/refresh allowing to generate a new access token. Authenticate to the backend by providing the API key expected by the server. If authentication succeeds, the endpoint returns a json embedding an access token and a refresh token (JSON Web Tokens). The access token must be passed as an argument or in the `Authorization` HTTP header for all later calls to the backend (account & pushtx REST API + websockets). The refresh token must be passed as an argument or in the `Authorization` HTTP header for later calls to /auth/refresh allowing to generate a new access token.
Authentication is activated in /keys/inndex.js configuration file Authentication is activated in /keys/index.js configuration file
``` ```
auth: { auth: {
@ -44,6 +44,9 @@ auth: {
POST /auth/login POST /auth/login
``` ```
The API Key must be passed in the body of the request as an url encoded argument.
## Parameters ## Parameters
* **apikey** - `string` - The API key securing access to the backend * **apikey** - `string` - The API key securing access to the backend
@ -51,7 +54,9 @@ POST /auth/login
### Example ### Example
``` ```
POST /auth/login?apikey=myAPIKey POST /auth/login
apikey=myAPIKey
``` ```
#### Success #### Success

9
doc/POST_auth_refresh.md

@ -1,12 +1,15 @@
# Refresh the access token # Refresh the access token
Request a new access token from the backend. A valid refresh token must be passed as an argument or through the `Authorization` HTTP header (with the `Bearer` scheme). Request a new access token from the backend.
``` ```
POST /auth/refresh POST /auth/refresh
``` ```
The Refresh Token must be passed in the body of the request as an url encoded argument or through the `Authorization` HTTP header (with the `Bearer` scheme).
## Parameters ## Parameters
* **rt** - `string` - A valid refresh token * **rt** - `string` - A valid refresh token
@ -14,7 +17,9 @@ POST /auth/refresh
### Example ### Example
``` ```
POST /auth/refresh?rt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTYW1vdXJhaSBXYWxsZXQgYmFja2VuZCIsInR5cGUiOiJyZWZyZXNoLXRva2VuIiwiaWF0IjoxNTQ0MTAzOTI5LCJleHAiOjE1NDQxMTExMjl9.6gykKq31WL4Jq7hfmoTwi1fpmBTtAeFb4KjfmSO6l00 POST /auth/refresh
rt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTYW1vdXJhaSBXYWxsZXQgYmFja2VuZCIsInR5cGUiOiJyZWZyZXNoLXRva2VuIiwiaWF0IjoxNTQ0MTAzOTI5LCJleHAiOjE1NDQxMTExMjl9.6gykKq31WL4Jq7hfmoTwi1fpmBTtAeFb4KjfmSO6l00
``` ```
#### Success #### Success

1
doc/POST_pushtx.md

@ -10,6 +10,7 @@ POST /pushtx/
* **tx** - `hex string` - The raw transaction hex * **tx** - `hex string` - The raw transaction hex
* **at** - `string` (optional) - Access Token (json web token). Required if authentication is activated. Alternatively, the access token can be passed through the `Authorization` HTTP header (with the `Bearer` scheme). * **at** - `string` (optional) - Access Token (json web token). Required if authentication is activated. Alternatively, the access token can be passed through the `Authorization` HTTP header (with the `Bearer` scheme).
### Example ### Example
``` ```

3
doc/POST_pushtx_schedule.md

@ -7,6 +7,9 @@ Schedule the delayed push of an ordered list of transactions (used for programma
POST /pushtx/schedule POST /pushtx/schedule
``` ```
Parameters must be passed in the body of the request as json encoded arguments.
## Parameters ## Parameters
* **script** - `ScriptStep[]` - An array of ScriptStep objects defining the script. * **script** - `ScriptStep[]` - An array of ScriptStep objects defining the script.

11
doc/POST_xpub.md

@ -4,10 +4,14 @@ Notify the server of the new HD account for tracking. When new accounts are sent
Response time for restored accounts might be long if there is much previous activity. Response time for restored accounts might be long if there is much previous activity.
``` ```
POST /xpub POST /xpub
``` ```
Parameters must be passed in the body of the request as url encoded arguments.
## Parameters ## Parameters
* **xpub** - `string` - The extended public key for the HD Account * **xpub** - `string` - The extended public key for the HD Account
* **type** - `string` - Whether this is a newly-created account or one being restored. Recognized values are `'new'` and `'restore'`. * **type** - `string` - Whether this is a newly-created account or one being restored. Recognized values are `'new'` and `'restore'`.
@ -15,12 +19,13 @@ POST /xpub
* **force** - `boolean` (optional) - Force an override of derivation scheme even if xpub is locked. Used for `'restore'` operation. * **force** - `boolean` (optional) - Force an override of derivation scheme even if xpub is locked. Used for `'restore'` operation.
* **at** - `string` (optional) - Access Token (json web token). Required if authentication is activated. Alternatively, the access token can be passed through the `Authorization` HTTP header (with the `Bearer` scheme). * **at** - `string` (optional) - Access Token (json web token). Required if authentication is activated. Alternatively, the access token can be passed through the `Authorization` HTTP header (with the `Bearer` scheme).
### Example ### Example
``` ```
POST /xpub?xpub=xpub0123456789&type=restore POST /xpub
POST /xpub?xpub=xpub0123456789&type=new&segwit=bip49
POST /xpub?xpub=xpub0123456789&type=restore&segwit=bip84 xpub=xpub0123456789&type=restore&segwit=bip84
``` ```
#### Success #### Success

9
doc/POST_xpub_lock.md

@ -2,20 +2,27 @@
To avoid errors related to `POST xpub` and SegWit derivation type, this endpoint allows locking of the type of an xpub in the database. To avoid errors related to `POST xpub` and SegWit derivation type, this endpoint allows locking of the type of an xpub in the database.
``` ```
POST /xpub/:xpub/lock POST /xpub/:xpub/lock
``` ```
Parameters must be passed in the body of the request as url encoded arguments.
## Parameters ## Parameters
* **address** - `string` - The first address of the internal chain for this `xpub`, derivation path `M/1/0`. Use compressed P2PHK address regardless of HD derivation scheme. * **address** - `string` - The first address of the internal chain for this `xpub`, derivation path `M/1/0`. Use compressed P2PHK address regardless of HD derivation scheme.
* **message** - `string` - Either `"lock"` or `"unlock"` * **message** - `string` - Either `"lock"` or `"unlock"`
* **signature** - `string` - The base64-encoded signature of the double SHA256 hash of `[varuint length of message string, message string]`. Signature scheme follows [bitcoinjs-message](https://github.com/bitcoinjs/bitcoinjs-message/blob/master/index.js) with a message prefix matching the [coin type](https://github.com/bitcoinjs/bitcoinjs-lib/blob/v3.1.1/src/networks.js). Use the ECPair associated with the `M/1/0` address to sign. * **signature** - `string` - The base64-encoded signature of the double SHA256 hash of `[varuint length of message string, message string]`. Signature scheme follows [bitcoinjs-message](https://github.com/bitcoinjs/bitcoinjs-message/blob/master/index.js) with a message prefix matching the [coin type](https://github.com/bitcoinjs/bitcoinjs-lib/blob/v3.1.1/src/networks.js). Use the ECPair associated with the `M/1/0` address to sign.
* **at** - `string` (optional) - Access Token (json web token). Required if authentication is activated. Alternatively, the access token can be passed through the `Authorization` HTTP header (with the `Bearer` scheme). * **at** - `string` (optional) - Access Token (json web token). Required if authentication is activated. Alternatively, the access token can be passed through the `Authorization` HTTP header (with the `Bearer` scheme).
### Example ### Example
``` ```
POST /xpub/xpub0123456789/lock?address=1address&message=lock&signature=Base64X== POST /xpub/xpub0123456789/lock
address=1address&message=lock&signature=Base64X==
``` ```
#### Success #### Success

Loading…
Cancel
Save