n0rmz / ripple-rest

Tools to simplify Ripple transaction submission and monitoring

ripple-rest

A simplified RESTful API for interfacing with the Ripple Network.

See the Guide and the API Reference for details on how to use the API.

Setup

Test Instance

A test version of the API can be found at https://ripple-rest.herokuapp.com.

Even though the test API supports HTTPS connections, only submit transactions from test accounts, we make NO GUARANTEES about the security of your secret keys on this server.

Dependencies

1. Node.js
2. PostgreSQL (on a Mac use the app). Follow the instructions here or those that came with your PostgreSQL to get the database server running on your machine

Installing

1. Run git clone https://github.com/ripple/ripple-rest.git in a terminal and switch into the ripple-rest directory
2. Run npm install to install the dependencies and setup the database
3. Run node server.js to start the server
4. Visit http://localhost:5990/api/v1/status in your browser to confirm that the server is up and running

Updating

1. From the root ripple-rest directory run npm install to update to the newest version, update dependencies, and reconfigure the database
2. If the old version of the server is still running, kill the process with CTRL-C in the same terminal window where it is running or killall node to stop all Node.js processes on a Linux or Mac computer
3. Run node server.js to restart the server
4. Visit http://localhost:5990/api/v1/status in your browser to confirm that the server is up and running

Customization

• Configuration options are loaded from various sources according to the following hierarchy (where 1 is the highest priority):

  1. Command line options:

  node server.js --DATABASE_URL=postgres://ripple_rest_user:password@localhost:5432/ripple_rest_db

  2. Environment variables:

  export DATABASE_URL=postgres://ripple_rest_user:password@localhost:5432/ripple_rest_db; node server.js

  3. The config.json file, which follows the format of the config-example.json file:

  { 
    /* ... */
    DATABASE_URL: "postgres://ripple_rest_user:password@localhost:5432/ripple_rest_db" 
    /* ... */
  }

  For more information on the config.json file and its versions see docs/CONFIG.md.

• Configure the PostgreSQL connection by setting the DATABASE_URL field in any of the aforementioned configuration sources to a string in the following format: postgres://ripple_rest_user:password@localhost:5432/ripple_rest_db.

• Configure the rippled connection by setting the rippled_servers field to a JSON object of the form:

    "rippled_servers": [
      {
        "host": "s_west.ripple.com",
        "port": 443,
        "secure": true
      }
    ]

• Enable SSL by including the following in the config.json in any of the configuration sources:

  {
  /* ... */
    "ssl": {
      "key_path": "path/to/server.key",
      "cert_path": "path/to/server.crt"
    }
  /* ... */
  }

  Note that you will need to connect to the server with https:// if you have SSL enabled.

• If installing on Heroku you must add the Heroku PostgreSQL add-on first by running the command:

  heroku addons:add heroku-postgresql:dev

Testing

npm test

Bugs

This API is still in beta. Please open issues for any problems you encounter.

API Object Formats

1. Amount
2. Payment
3. Notification

Available API Routes

1. Notifications
   • GET /api/v1/addresses/:address/next_notification
   • GET /api/v1/addresses/:address/next_notification/:prev_tx_hash
2. Payments
   • GET /api/v1/addresses/:address/payments/:dst_address/:dst_amount
   • POST /api/v1/addresses/:address/payments
   • GET /api/v1/addresses/:address/payments/:tx_hash
3. Standard Ripple Transactions
   • GET /api/v1/addresses/:address/txs/:tx_hash
4. Server Info
   • GET /api/v1/status