Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Balanced's API Documentation

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
api
assets
balanced_docs
clients/rev1
overview/rev1
scripts
spec
.bowerrc
.gitignore
.gitmodules
.travis.yml
CONTRIBUTORS
Makefile
README.md
balanced.json
balanced.rev1.json
bower.json
custom_htmltranslations.py
package.json
requirements.txt
scenario.cache
setup.py

README.md

Balanced Docs

Build Status

This project builds the following Balanced documentation:

Contributing

All contributions, even simple grammar fixes, are greatly appreciated.

  1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
  2. Fork the repository on Github to start making your changes to the develop branch (or branch off of it).
  3. Send a pull request!

Make sure to add yourself to CONTRIBUTORS. We will showcase the CONTRIBUTORS file on our COMMUNITY PAGE.

After your pull request, email support [@] balancedpayments.com with your address and the link to your pull request with your address and your t-shirt size so we can send you your very own Balanced t-shirt!

Setup

You'll first need:

And then you can setup your environment like this:

git clone git@github.com:balanced/balanced-docs.git
cd balanced-docs
git submodule update --init --recursive --remote
mkvirtualenv balanced-docs
python setup.py develop
pip install -r requirements.txt

If you've done that before just do:

cd /path/to/balanced-docs
workon balanced-docs
git submodule update --init --recursive --remote

Build

Now that your environment is setup, let's build the documentation. To build them all at once do:

make all

Specification

To build the specification do:

make spec

Overview

To build the overview do:

make overview

Reference

To build the reference do:

make api

Preview

Let's take a look at what we've built using mongoose:

cd build
mongoose
// Mongoose web server v. 3.8 started on port(s) 8080 with web root [.]

Specification

Open up http://localhost:8080/spec

Overview

Open up http://localhost:8080/overview.shtml

Reference

Open up http://localhost:8080/api.shtml

Hacking

rST

All of the documentation is written in r(e)S(tructured)T(ext) which you can read about here.

dcode

We've added a custom rST directive called dcode which uses external scripts to generate rST content. For example:

.. dcode:: scenario credit_create_new_bank_account

Here we are asking dcode to run the credit_create_new_bank_account. The output for that scenario will end up in place of the directive.

You'll also see a corresponding dcode-default directive. For example:

.. dcode-default:: scenario
    :script: ../scenario.py -d ../scenarios -c scenario.cache
    :section-chars: ~^
    :lang: ruby

Which registers an external script for scenario. As a result the dcode directive above will result in this call:

../scenario.py -d ../scenarios -c scenario.cache credit_create_new_bank_account --lang ruby

Run individual scenario

scripts/lang-scenario.py -d clients/{REVISION}/curl hold_create

Edit field descriptions for scenarios

Field descriptions are from balanced.rev1.json, which are generated from balanced-api. The "forms" used in balanced-docs are assembled from parameters supplied in the scenarios in balanced-api. Those scenarios should be updated to include the fields missing the specific scenario section and a newly generated balanced.rev1.json be committed into the docs. To generate balanced.rev1.json in balanced-api run:

bundle exec rake features:all

DO NOT run

bundle exec rake parallel:features

doing so causes the file to overwrite itself.

Something went wrong with that request. Please try again.