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

picatrix

An opinionated hypermedia API generator. :grin:

Requires

• valid .dot file with additional style guidelines
• Protobuf definitions of inputs/outputs for all state transitions, by node

Outputs

• basic Sinatra app and mock objects fitting your schema
  • intended to be a scaffold for your client to immediately test against, and maybe for you to build from or to (to as in match its interface in contract)
  • application/vnd.mason+json hypermedia affordances
  • CRUD + Filter actions are defined for you by default
  • $select and $expand URL conventions apply
• state diagram image (see below)

Installation

Install system dependencies (Mac OS sample):

$ brew install graphviz
$ brew install protobuf

Add this line to your application's Gemfile:

gem 'picatrix'

And then execute:

$ bundle

Or install it yourself as:

$ gem install picatrix

getting ready

• easiest thing to do is use the rake task provided to make yourself a copy of the sample dot file which you can edit

.dot file styles

• edge style defaults to arrowhead=odiamond to signify default requests are GET
• the first node listed should be the root, and is signified by xlabel= and shape=point, you should never need to change this (unless you are knitting together workflows - future thing)
• collection nodes should be given shape=folder and pluralized
• the item node belonging to the collection node should be its singularized version and shape=rectangle
• style=bold and arrowhead=normal means POST
• arrowhead=normal alone means PATCH
• color=red fontcolor=red means DELETE

protobuf definitions of representations

• must match the node names (each node signifies a representation)
• consider
  • from the perspective of the client at any request, what does it need to make the request and have the server fufill its contract?
  • from the perspective of the server, what might the client want in response for it to make any interesting subsequent requests from this node in the workflow?
  • inputs will map onto controls, and outputs will map on to representations (dereferenced content)

Usage

$ bin/picapica prep dg_api.dot app_name
=> generated/app_name.proto
# at this point you flesh out your schema in your proto file
$ vi generated/app_name.proto
$ bin/picapica g 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

how to interpret the graph

Nodes and edges translate roughly into application and/or resource states, and state transitions. Labels on edges are link relations.

see also

more notes

License

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