ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 19:55:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

[DOC] REST - expanded and restructured setup instructions

Browse Source
This commit is contained in:
mDuo13
2014-11-19 13:27:32 -08:00
parent daec5d512e
commit 50a5fc6ae1
1 changed files with 108 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
content/ripplerest_api.md
View File

@@ -4,8 +4,6 @@ The Ripple-REST API provides a simplified, easy-to-use interface to the Ripple N
We recommend Ripple-REST for users just getting started with Ripple, since it provides high-level abstractions and convenient simplifications in the data format. If you prefer to access a `rippled` server directly, you can use [rippled's WebSocket or JSON-RPC APIs](rippled-apis.html) instead, which provide the full power of Ripple at the cost of more complexity. We recommend Ripple-REST for users just getting started with Ripple, since it provides high-level abstractions and convenient simplifications in the data format. If you prefer to access a `rippled` server directly, you can use [rippled's WebSocket or JSON-RPC APIs](rippled-apis.html) instead, which provide the full power of Ripple at the cost of more complexity.
Installation instructions and source code can be found in the [Ripple-REST repository](https://github.com/ripple/ripple-rest).
## Available API Routes ## ## Available API Routes ##
@@ -95,24 +93,21 @@ You can create client resource IDs using any method you like, so long as you fol
You can use the [Create Client Resource ID](#create-client-resource-id) method in order to generate new Client Resource IDs. You can use the [Create Client Resource ID](#create-client-resource-id) method in order to generate new Client Resource IDs.
## Getting Started ## ## Using Ripple-REST ##
### Setup ###
You don't need to do any setup to retrieve information from a public Ripple-REST server. Ripple Labs hosts a public Ripple-REST server here: You don't need to do any setup to retrieve information from a public Ripple-REST server. Ripple Labs hosts a public Ripple-REST server here:
`https://api.ripple.com` `https://api.ripple.com`
However, in order to submit payments or other transactions, you need an activated Ripple account. See the [online support](https://support.ripplelabs.com/hc/en-us/categories/200194196-Set-Up-Activation) for how you can create an account using the [Ripple Trade client](https://rippletrade.com/). If you want to run your own Ripple-REST server, see the [installation instructions](#running-ripple-rest).
In order to submit payments or other transactions, you need an activated Ripple account. See the [online support](https://support.ripplelabs.com/hc/en-us/categories/200194196-Set-Up-Activation) for how you can create an account using the [Ripple Trade client](https://rippletrade.com/).
Make sure you know both the account address and the account secret for your account: Make sure you know both the account address and the account secret for your account:
* The *address* can be found by clicking the *Show Address* button in the __Fund__ tab of Ripple Trade * The *address* can be found by clicking the *Show Address* button in the __Fund__ tab of Ripple Trade
* The *secret* is provided when you first create your account. **WARNING: If you submit your secret to a server you do not control, your account can be stolen, along with all the money in it.** We recommend using a test account with very limited funds on the public Ripple-REST server. * The *secret* is provided when you first create your account. **WARNING: If you submit your secret to a server you do not control, your account can be stolen, along with all the money in it.** We recommend using a test account with very limited funds on the public Ripple-REST server.
If you want to run your own Ripple-REST server, see the [installation instructions](https://github.com/ripple/ripple-rest/#installing-and-running).
As a programmer, you will also need to have a suitable HTTP client that allows you to make secure HTTP (`HTTPS`) GET and POST requests. For testing, there are lots of options, including: As a programmer, you will also need to have a suitable HTTP client that allows you to make secure HTTP (`HTTPS`) GET and POST requests. For testing, there are lots of options, including:
* The [`curl`](http://curl.haxx.se/) commandline utility * The [`curl`](http://curl.haxx.se/) commandline utility
@@ -123,92 +118,6 @@ You can also use the [REST API Tool](rest-api-tool.html) here on the Dev Portal
[Try it! >](rest-api-tool.html) [Try it! >](rest-api-tool.html)
### Quick Start ###
`ripple-rest` requires Node.js and uses sqlite3 as it's database.
Follow these instructions to get your `ripple-rest` server installed and running
1. Run `git clone https://github.com/ripple/ripple-rest.git` in a terminal and switch into the `ripple-rest` directory
2. Install dependencies needed: `npm install`
3. Copy the config example to config.json: `cp config-example.json config.json`
5. Run `node server.js` to start the server
6. Visit [`http://localhost:5990`](http://localhost:5990) to view available endpoints and to get started
## Configuring `ripple-rest` ###
The `ripple-rest` server loads configuration options from the following sources, according to the following hierarchy (where options from 1. override those below it):
1. Command line arguments
2. Environment variables
3. The `config.json` file
The path to the `config.json` file can be specified as a command line argument (`node server.js --config /path/to/config.json`). If no path is specified, the default location for that file is in `ripple-rest`'s root directory.
Available configuration options are outlined in the [__Server Configuration__](docs/server-configuration.md) document and an example configuration file is provided [here](config-example.json).
`ripple-rest` uses the [nconf](https://github.com/flatiron/nconf) configuration loader so that any options that can be specified in the `config.json` file can also be specified as command line arguments or environment variables.
## Debug mode ##
The server can be run in Debug Mode by running `node server.js --debug`.
## Running ripple-rest securely over SSL ##
1. Create SSL certificate to encrypt traffic to and from the `ripple-rest` server.
```bash
openssl genrsa -out /etc/ssl/private/server.key 2048
openssl req -utf8 -new -key /etc/ssl/private/server.key -out /etc/ssl/server.csr -sha512
-batch
openssl x509 -req -days 730 -in /etc/ssl/server.csr -signkey /etc/ssl/private/server.key
-out /etc/ssl/certs/server.crt -sha512
```
2. Modify the `config.json` to enable SSL and specify the paths to the `certificate` and `key` files
```
"ssl_enabled": true,
"ssl": {
"key_path": "./certs/server.key",
"cert_path": "./certs/server.crt"
},
```
## Deployment tips
Run `ripple-rest` using [`forever`](https://www.npmjs.org/package/forever). `node` and `npm` are required. Install `forever` using `sudo npm install -g forever`.
Example of running `ripple-rest` using `forever`:
```
forever start \
--pidFile /var/run/ripple-rest/ripple-rest.pid \
--sourceDir /opt/ripple-rest \
-a -o /var/log/ripple-rest/ripple-rest.log \
-e /var/log/ripple-rest/ripple-rest.err \
-l /var/log/ripple-rest/ripple-rest.for \
server.js
```
Monitor `ripple-rest` using [`monit`](http://mmonit.com/monit/). On Ubuntu you can install `monit` using `sudo apt-get install monit`.
Example of a monit script that will restart the server if:
- memory goes up over 25%
- the server fails responding to server status
```
set httpd port 2812 and allow localhost
check process ripple-rest with pidfile /var/run/ripple-rest/ripple-rest.pid
start program = "/etc/init.d/ripple-rest start"
stop program = "/etc/init.d/ripple-rest stop"
if memory > 25% then restart
if failed port 5990 protocol HTTP
and request "/v1/server"
then restart
```
### Exploring the API ### ### Exploring the API ###
A REST API makes resources available via HTTP, the same protocol used by your browser to access the web. This means you can even use your browser to get a response from the API. Try visiting the following URL: A REST API makes resources available via HTTP, the same protocol used by your browser to access the web. This means you can even use your browser to get a response from the API. Try visiting the following URL:
@@ -254,6 +163,110 @@ http://localhost:5990/v1/server
Since the hostname depends on where your chosen Ripple-REST instance is, the methods in this document are identified using only the part of the path that comes after the hostname. Since the hostname depends on where your chosen Ripple-REST instance is, the methods in this document are identified using only the part of the path that comes after the hostname.
# Running Ripple-REST #
## Quick Start ##
Ripple-REST requires [Node.js](http://nodejs.org/) and [sqlite 3](http://www.sqlite.org/). Before starting, you should make sure that you have both installed.
Following that, use these instructions to get Ripple-REST installed and running:
1. Clone the Ripple-REST repository with git:
`git clone https://github.com/ripple/ripple-rest.git`
2. Switch to the `ripple-rest` directory:
`cd ripple-rest`
3. Use *npm* to install additional dependencies:
`npm install`
4. Copy the example config file to `config.json`:
`cp config-example.json config.json`
5. Start the server:
`node server.js`
6. Visit [http://localhost:5990](http://localhost:5990) in a browser to view available endpoints and get started
## Configuring `ripple-rest` ##
The Ripple-REST server uses [nconf](https://github.com/flatiron/nconf) to load configuration options from several sources. Settings from sources earlier in the following hierarchy override settings from the later levels:
1. Command line arguments
2. Environment variables
3. The `config.json` file
The path to the `config.json` file can be specified as a command line argument (`node server.js --config /path/to/config.json`). If no path is specified, the default location for that file is Ripple-REST's root directory.
Available configuration options are outlined in the [__Server Configuration__](https://github.com/ripple/ripple-rest/blob/develop/docs/server-configuration.md) document. The `config-example.json` file in the root directory contains a sample configuration.
## Debug mode ##
The server can be run in Debug Mode by running `node server.js --debug`.
## Running Ripple-REST securely over SSL ##
We highly recommend running Ripple-REST securely over SSL. Doing so requires a certificate. For development and internal-only deployments, you can use a self-signed certificate. For production servers that are accessed over untrusted network connections, you should purchase a cert from a proper authority.
You can perform the following steps to generate a self-signed cert with [OpenSSL](https://www.openssl.org/) and configure Ripple-REST to use it:
1. Generate the SSL certificate:
```bash
openssl genrsa -out /etc/ssl/private/server.key 2048
openssl req -utf8 -new -key /etc/ssl/private/server.key -out /etc/ssl/server.csr -sha512
-batch
openssl x509 -req -days 730 -in /etc/ssl/server.csr -signkey /etc/ssl/private/server.key
-out /etc/ssl/certs/server.crt -sha512
```
2. Modify the `config.json` to enable SSL and specify the paths to the `certificate` and `key` files
```
"ssl_enabled": true,
"ssl": {
"key_path": "./certs/server.key",
"cert_path": "./certs/server.crt"
},
```
## Deployment Tips ##
### Keeping the service running ###
To make sure that the Ripple-REST process remains active even if it crashes for some reason, use the [`forever`](https://www.npmjs.org/package/forever) Node module. Install `forever` using `sudo npm install -g forever`.
Here is an example of running `ripple-rest` using `forever`:
```
forever start \
--pidFile /var/run/ripple-rest/ripple-rest.pid \
--sourceDir /opt/ripple-rest \
-a -o /var/log/ripple-rest/ripple-rest.log \
-e /var/log/ripple-rest/ripple-rest.err \
-l /var/log/ripple-rest/ripple-rest.for \
server.js
```
### Monitoring the service ###
Monitor `ripple-rest` using [`monit`](http://mmonit.com/monit/). On Ubuntu you can install `monit` using `sudo apt-get install monit`.
Here is an example of a monit script that will restart the server if:
- memory usage surpasses 25% of the server's available memory
- the server fails responding to server status
```
set httpd port 2812 and allow localhost
check process ripple-rest with pidfile /var/run/ripple-rest/ripple-rest.pid
start program = "/etc/init.d/ripple-rest start"
stop program = "/etc/init.d/ripple-rest stop"
if memory > 25% then restart
if failed port 5990 protocol HTTP
and request "/v1/server"
then restart
```
# Formatting Conventions # # Formatting Conventions #