apidragon: an Api Interaction Automation Framework

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

Requirements:

• 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)

Configuration:

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:password@test.net/api/test.do input: - id output: - tablename mode: get testcall2: function: username:password@test.net/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.

plugin

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:
  ```yaml
  vars:
    test: test
  example:
    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

stdout

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

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

record

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.

logging

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

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

plugin

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
  end

  - apidragonconf.yaml  
  ```yaml
  testcall:
    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

License

MIT