Balanced API Specification
This repository contains an executable specification of the Balanced API. The goal of this repository is two-fold. First, to ensure that the API is working according to the spec. Second, to provide a place to have discussions around the API as a product.
An Executable Specification
Specifications don't matter if they're not followed. Therefore, this
specification is executable, so we can ensure conformance to the spec. There are
more details in the README file inside the
features directory, but to run these
tests yourself, simply:
$ git clone https://github.com/balanced/balanced-api.git $ cd balanced-api $ bundle $ bin/rake cucumber
This requires Ruby. We run the changes with Ruby 2.0, but other versions will probably work as well. Let us know if you have any problems running these specs, and we'd be happy to help.
If you're working on a new scenario, the 'focus' task is useful. Tag a scenario
@focus, and then run
bin/rake focus. It will only run that single scenario.
Discussions around changes
Speaking of issues, that's the second purpose of this repository. If you would like to see a new feature implemented in the Balanced API, please open an issue and we'll discuss it.
For example, one of our biggest requests is to support non-USD currencies. Here is the issue with the discussion, and when we support this feature, we close the issue via a pull request that implements the specification, and then everyone on the issue gets notified.
Sometimes, Issues are great for collecting feedback, as well. For example, all implementation of the current framework was done via PR, and some issues need more explanation around use cases by those who want the feature, like Bitcoin support.
We try to do as much 'internal' discussion in these issues as well, it's not just for public feedback. If you want to know what we're thinking, just search for a relevant issue!
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.