apidragon: an Api Interaction Automation Framework

Code Climate

These classes run a sequence of API calls using a configuration file.

  • config file is read and vars are dumped into an arg_bucket
  • macros are specified in the config and can be run from the command line


  • Ruby > 2.0
  • Gems: json, active_support, psych, rest-client

How to Use:

  • gem install apidragon
  • Create apidragonconf.yaml according to the examples below
  • Run from the command line with apidragon do [command]
    [command] is the name of one of the macros defined in the config file. So if I was using the config in the example,
    I could run apidragon do macro_1, which would then call testcall and testcall2 in the order specified.
  • You can specify your own config file path by running apidragon do [command] --config [filepath]
  • You can specify you password or username from the command line with apidragon do [command] --username [username] --password [password] (recommended if you don't want to store credentials in a file)


Create apidragonconf.yaml. It can contain any variables you need to access the API you are using, as well as macros.

  • Example config: yaml --- vars: test: value username: bob password: mypassword id: 123456abcdef macros: macro_1: testcall: function: username:[email protected]/api/test.do input: - id output: - tablename mode: get testcall2: function: username:[email protected]/api/test2.do input: - tablename output: - tablecontents mode: get

Each macro can have n number of calls like testcall in the example, each requiring a function, the necessary input and output variables, and the request mode.

Request modes

Currently supported modes:

  • get
  • post
  • put
  • delete
  • curl_get, curl_post (uses curl instead of the rest-client gem for special cases)
  • plugin
  • Planned: curl_put, curl_delete

get, post, put, delete

Makes an api call using the respective HTTP verb through the rest-client gem.

curl_get, curl_post

Makes an api call using the respective HTTP verb through curl.


Evaluates the given line of ruby code through eval().

  • e.g.:

    • Plugin.rb (@/tmp/apidragonplugins/): ```ruby class Plugin def initialize(message) @message = message end

    def run puts "This is a test, here are my args: \n #@message" end end

    Notes: Filename and classname are arbitrary but should be the same as each other. Plugins must contain the above initialize method and a run method which can call any code desired.
    - apidragonconf.yaml:
      test: test
        function: Plugin # apidragon will attempt to load the class, call .new passing the @arg_bucket and then calling .run
        plugin: Plugin # loads this file from /tmp/apidragonplugins/ 
        mode: plugin
    • ouput of apidragon do example: This is a test, here are my args: {"test" => "test"}

Further Options


Setting stdout: true for any call will ouput its response to STDOUT. Defaults to false.

  • e.g.: yaml testcall: stdout: true


Each call can have a record option, where you can specify what output variables you want to record to your config.

  • e.g.: yaml testcall: output: - id - userinfo record: - id

Qualifier variables

apidragon automatically returns the first instance it finds of the specified output variable in the response.

For more specific output parsing, you can specify a qualifier variable. As long as responses are returned as xml or json, output variables can be associated with one of your pre-defined values for cases like parsing lists of values that have several attribute fields.

  • e.g.: yaml testcall: output: - id: username - userinfo So if the call returns a list like this: [{username => bob, id => 1234}, {username => alice, id => 5678}], you can always return the id associated with the username variable defined in the vars section.


Loggin can be disabled by specifying logging to be false, as per below.

  • e.g.: yaml testcall: logging: false


Note: The default folder for plugins is /usr/local/apidragonplugins. Create this folder and writing any plugin files to it usually requires root permissions. Each call can refer to a plugin file. The Plugin class should follow the structure outlined below.

  • e.g.:

    • example.rb (@ /tmp/apidragonplugins/) ```ruby class Plugin # class must be named Plugin def initialize(message) # pass only one parameter, which will be equal to the body of the call's http response @message = message end

    def run # main function must be named run and take no parameters. Run all your operations from here puts @message end

    - apidragonconf.yaml  
      plugin: example #name of file minus .rb extension

To-Do / Planned Features

  • Ability to pass any variables as options at the command line
  • Unit Tests