# apidragon: an Api Interaction Automation Framework
[![Code Climate](https://codeclimate.com/github/isand3r/apidragon/badges/gpa.svg)](https://codeclimate.com/github/isand3r/apidragon)

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 `/tmp/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 `/tmp/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.:
  - test.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
  ```
  - apidragonconf.yaml:
  ```yaml
    vars:
      test: test
    example:
      test:
        function: Plugin.new(@arg_bucket).run # initializes and calls the run function for my Plugin class, passing the arg_bucket.
        plugin: test
        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
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
  ```


# Planned Features
- Support for multiple instances of variable names for different api's

#License

[MIT](https://tldrlegal.com/license/mit-license)