.--.
    /( @ >    ,-.
   / ' .'--._/  /
   :   ,    , .'
   '. (___.'_/
    ((-((-''mrf

Picatrix

An opinionated hypermedia API generator.

Requires:

  • valid .dot file (with some specific styles)

Outputs:

  • Sinatra style routes
  • application/vnd.mason+json assets
    • serializers
    • templates (think forms, not views)
  • state diagram image (see below)

About

Directed graphs get complicated, but can be divded into simpler subgraphs. Picatrix is currently useful for only a single workflow (and barely that right now, as we're way before a real release). Integrated workflows will involve generating several route sets that will be required into a single Sinatra app. Some workflows may even be representable as DAGs/trees.

The ideal way to use Picatrix is to do an exercise in designing your API "outside in" where all inputs/outputs are defined, and a state diagram is drawn. This diagram can be translated to a dot file, and the inputs/outputs can be translated into hypermedia assets.

Installation

Add this line to your application's Gemfile:

gem 'picatrix'

And then execute:

$ bundle

Or install it yourself as:

$ gem install picatrix

Usage

In its final state, the intent is to use it as a CLI:

$ bin/picapica dg_api.dot app_name
=> generated/app_name.rb

Sample Image Output

# to generate the image with graphviz installed
$ dot -Tpng spec/support/dg_api.dot -o spec/support/dg_api.dot.png

state diagram image of sample app

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

TODO

  • generate sinatra routes from app & resource edges
    • initially make mason stubs myself
    • usage will be to iteratively make the necessary templates until routes are filled out
  • with all mason stubs established, make generators for them from
    • RAML?
    • json
    • yml?

done

  • parse dot file in Ruby

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.