esp_sdk 1.1.0 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9ae3ded6473c7dd46addd90c607bc9f9a33e6c56
-  data.tar.gz: 4528c438187d057bb6a6062e6f9999968a3a0c92
+  metadata.gz: 375b1160781a13a88cefd9a083eff938b826902d
+  data.tar.gz: 16a16aefa8bec1cde0b74c74de232700ed77bbd1
 SHA512:
-  metadata.gz: 5af81ffd9e432e288418a7e7fcb766b853f15e85e3f1079ee2526526d0eb520c5006f929ea36e6c3b96c410a33366371becfcc36329fd1851662b22cb1636a53
-  data.tar.gz: d88b77ff17a2d27ce65b3f58ef6cd1affc06deb2e757db1f186355a8059b3e9c48c2fbd4ddf38d9001e3af639e80321786b8e339446c964c3f323be6920602fc
+  metadata.gz: 6f7342eb640fb5eb04e02e0bab60b7e7ed7b8073cccab9c9d5759faac55762c711191f4ce63581e64131be3b7ed8b47335da5e1f5091704993ce6de70e7b3908
+  data.tar.gz: 9da7a80cff4b9ee24e24a804f4a68191887bc73ec4f6a10f19763936209179fa802762608f27ce90ba9362b1688acba52f4aab010d29cb227f9e8a418604172c

data/.gitignore

@@ -3,14 +3,12 @@
 .bundle
 .config
 .yardoc
-Gemfile.lock
 InstalledFiles
 _yardoc
 coverage
 doc/
 lib/bundler/man
 pkg
-rdoc
 spec/reports
 test/tmp
 test/version_tmp

data/.rubocop.yml

@@ -89,7 +89,7 @@ Style/BlockComments:
 Style/BlockEndNewline:
   Enabled: true
 
-Style/Blocks:
+Style/BlockDelimiters:
   Enabled: true
 
 
@@ -236,10 +236,10 @@ Style/EvenOdd:
   Enabled: true
 
 Style/ExtraSpacing:
-  Enabled: false
+  Enabled: true
 
 Style/FileName:
-  Enabled: false
+  Enabled: true
   Exclude:
     - '**/Rakefile'
     - '**/Gemfile'
@@ -308,6 +308,10 @@ Style/IndentHash:
 Style/InfiniteLoop:
   Enabled: true
 
+Style/InitialIndentation:
+  Description: Checks the indentation of the first non-blank non-comment line in a file.
+  Enabled: true
+
 Style/Lambda:
   Enabled: true
 
@@ -405,6 +409,12 @@ Style/NumericLiterals:
 Style/OneLineConditional:
   Enabled: true
 
+Style/OptionalArguments:
+  Enabled: true
+
+Style/OptionHash:
+  Enabled: true
+
 Style/OpMethod:
   Enabled: true
 
@@ -412,6 +422,9 @@ Style/ParenthesesAroundCondition:
   Enabled: true
   AllowSafeAssignment: true
 
+Style/ParallelAssignment:
+  Enabled: true
+
 Style/PercentLiteralDelimiters:
   Enabled: true
   PreferredDelimiters:
@@ -467,7 +480,10 @@ Style/RedundantSelf:
 
 Style/RegexpLiteral:
   Enabled: true
-  MaxSlashes: 1
+
+Style/RescueEnsureAlignment:
+  Description: 'Align rescues and ensures correctly.'
+  Enabled: true
 
 Style/RescueModifier:
   Enabled: true
@@ -479,6 +495,12 @@ Style/Semicolon:
   Enabled: true
   AllowAsExpressionSeparator: false
 
+Style/Send:
+  Description: 'Prefer `Object#__send__` or `Object#public_send` to `send`, as `send` may overlap with existing methods.'
+  StyleGuide: 'https://github.com/bbatsov/ruby-style-guide#prefer-public-send'
+  # TODO: enable this
+  Enabled: false
+
 Style/SignalException:
   Enabled: true
   EnforcedStyle: semantic
@@ -582,11 +604,14 @@ Style/SpaceInsideParens:
 Style/SpaceInsideRangeLiteral:
   Enabled: true
 
+Style/SpaceInsideStringInterpolation:
+  Enabled: true
+
 Style/SpecialGlobalVars:
   Enabled: true
 
 Style/StringLiterals:
-  Enabled: true
+  Enabled: false
   EnforcedStyle: single_quotes
   SupportedStyles:
     - single_quotes
@@ -618,6 +643,9 @@ Style/TrailingComma:
     - comma
     - no_comma
 
+Style/TrailingUnderscoreVariable:
+  Enabled: true
+
 Style/TrailingWhitespace:
   Enabled: true
 
@@ -654,7 +682,7 @@ Style/UnneededCapitalW:
 Style/UnneededPercentQ:
   Enabled: true
 
-Style/UnneededPercentX:
+Style/CommandLiteral:
   Enabled: true
 
 Style/VariableInterpolation:
@@ -722,6 +750,9 @@ Metrics/MethodLength:
   CountComments: false  # count full line comments?
   Max: 10
 
+Metrics/ModuleLength:
+  Enabled: true
+
 Metrics/ParameterLists:
   Enabled: true
   Max: 5
@@ -748,6 +779,9 @@ Lint/AssignmentInCondition:
 Lint/BlockAlignment:
   Enabled: true
 
+Lint/CircularArgumentReference:
+  Enabled: true
+
 Lint/ConditionPosition:
   Enabled: true
 
@@ -767,6 +801,9 @@ Lint/DeprecatedClassMethods:
 Lint/DuplicateMethods:
   Enabled: true
 
+Lint/EachWithObjectArgument:
+  Enabled: true
+
 Lint/ElseLayout:
   Enabled: true
 
@@ -792,6 +829,10 @@ Lint/EnsureReturn:
 Lint/Eval:
   Enabled: true
 
+Lint/FormatParameterMismatch:
+  Description: 'The number of parameters to format/sprint must match the fields.'
+  Enabled: true
+
 Lint/HandleExceptions:
   Enabled: true
 
@@ -807,6 +848,9 @@ Lint/LiteralInInterpolation:
 Lint/Loop:
   Enabled: true
 
+Lint/NestedMethodDefinition:
+  Enabled: true
+
 Lint/ParenthesesAsGroupedExpression:
   Enabled: true
 
@@ -828,6 +872,9 @@ Lint/StringConversionInInterpolation:
 Lint/UnderscorePrefixedVariableName:
   Enabled: true
 
+Lint/UnneededDisable:
+  Enabled: true
+
 Lint/UnusedBlockArgument:
   Enabled: true
 

data/.ruby-version

@@ -1 +1 @@
-2.1.5
+2.0.0

data/.travis.yml

@@ -1,9 +1,15 @@
+sudo: false
+cache: bundler
 language: ruby
 rvm:
-  - 2.1.1
-cache: bundler
+  - 2.0.0
+  - 2.1
+  - 2.2
 script:
   - bundle exec rake test
+  - bundle exec rake coveralls:push
+  - bundle exec rubocop
+
 addons:
   code_climate:
     repo_token: 73b22e855ca36fc2ab337552731c44437923bdf96780beb01c04c0fe2775f7a1

data/Gemfile.lock

@@ -0,0 +1,171 @@
+PATH
+  remote: .
+  specs:
+    esp_sdk (2.0.0.rc1)
+      activeresource (~> 4.0.0)
+      api-auth
+      artii
+      awesome_print
+      catpix
+      rack
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (4.2.1)
+      activesupport (= 4.2.1)
+      builder (~> 3.1)
+    activeresource (4.0.0)
+      activemodel (~> 4.0)
+      activesupport (~> 4.0)
+      rails-observers (~> 0.1.1)
+    activesupport (4.2.1)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    addressable (2.3.8)
+    ansi (1.5.0)
+    api-auth (1.3.2)
+    artii (2.1.1)
+    ast (2.0.0)
+    astrolabe (1.3.1)
+      parser (~> 2.2)
+    awesome_print (1.6.1)
+    bourne (1.6.0)
+      mocha (~> 1.1)
+    builder (3.2.2)
+    catpix (0.2.0)
+      docopt (~> 0.5, >= 0.5.0)
+      rmagick (~> 2.15, >= 2.15.2)
+      ruby-terminfo (~> 0.1, >= 0.1.1)
+      tco (~> 0.1, >= 0.1.8)
+    coderay (1.1.0)
+    coveralls (0.8.0)
+      multi_json (~> 1.10)
+      rest-client (>= 1.6.8, < 2)
+      simplecov (~> 0.9.1)
+      term-ansicolor (~> 1.3)
+      thor (~> 0.19.1)
+    crack (0.4.2)
+      safe_yaml (~> 1.0.0)
+    docile (1.1.5)
+    docopt (0.5.0)
+    factory_girl (4.5.0)
+      activesupport (>= 3.0.0)
+    ffi (1.9.10)
+    formatador (0.2.5)
+    guard (2.13.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, <= 4.0)
+      lumberjack (~> 1.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-minitest (2.4.4)
+      guard-compat (~> 1.2)
+      minitest (>= 3.0)
+    guard-rubocop (1.2.0)
+      guard (~> 2.0)
+      rubocop (~> 0.20)
+    i18n (0.7.0)
+    json (1.8.2)
+    listen (3.0.3)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    lumberjack (1.0.9)
+    metaclass (0.0.4)
+    method_source (0.8.2)
+    mime-types (2.4.3)
+    minitest (5.6.0)
+    minitest-reporters (1.0.11)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    mocha (1.1.0)
+      metaclass (~> 0.0.1)
+    multi_json (1.11.0)
+    nenv (0.2.0)
+    netrc (0.10.3)
+    notiffany (0.0.8)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    parser (2.2.2.5)
+      ast (>= 1.1, < 3.0)
+    powerpack (0.1.0)
+    pry (0.10.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rack (1.6.4)
+    rails-observers (0.1.2)
+      activemodel (~> 4.0)
+    rainbow (2.0.0)
+    rake (10.4.2)
+    rb-fsevent (0.9.6)
+    rb-inotify (0.9.5)
+      ffi (>= 0.5.0)
+    rdoc (4.0.0)
+    rest-client (1.7.3)
+      mime-types (>= 1.16, < 3.0)
+      netrc (~> 0.7)
+    rmagick (2.15.4)
+    rubocop (0.34.2)
+      astrolabe (~> 1.3)
+      parser (>= 2.2.2.5, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.4)
+    ruby-progressbar (1.7.5)
+    ruby-terminfo (0.1.1)
+    safe_yaml (1.0.4)
+    shellany (0.0.1)
+    shoulda (3.5.0)
+      shoulda-context (~> 1.0, >= 1.0.1)
+      shoulda-matchers (>= 1.4.1, < 3.0)
+    shoulda-context (1.2.1)
+    shoulda-matchers (2.8.0)
+      activesupport (>= 3.0.0)
+    simplecov (0.9.2)
+      docile (~> 1.1.0)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.9.0)
+    simplecov-html (0.9.0)
+    slop (3.6.0)
+    tco (0.1.8)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
+    thor (0.19.1)
+    thread_safe (0.3.5)
+    tins (1.3.5)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    webmock (1.21.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bourne
+  bundler
+  coveralls
+  esp_sdk!
+  factory_girl
+  guard
+  guard-minitest
+  guard-rubocop
+  minitest
+  minitest-reporters
+  mocha
+  rake
+  rdoc
+  rubocop
+  shoulda
+  webmock

data/Guardfile

@@ -0,0 +1,47 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+guard :minitest do
+  # with Minitest::Unit
+  watch(%r{^test/(.*)\/?test_(.*)\.rb$})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  watch(%r{^test/test_helper\.rb$})      { 'test' }
+
+  # with Minitest::Spec
+  # watch(%r{^spec/(.*)_spec\.rb$})
+  # watch(%r{^lib/(.+)\.rb$})         { |m| "spec/#{m[1]}_spec.rb" }
+  # watch(%r{^spec/spec_helper\.rb$}) { 'spec' }
+
+  # Rails 4
+  # watch(%r{^app/(.+)\.rb$})                               { |m| "test/#{m[1]}_test.rb" }
+  # watch(%r{^app/controllers/application_controller\.rb$}) { 'test/controllers' }
+  # watch(%r{^app/controllers/(.+)_controller\.rb$})        { |m| "test/integration/#{m[1]}_test.rb" }
+  # watch(%r{^app/views/(.+)_mailer/.+})                   { |m| "test/mailers/#{m[1]}_mailer_test.rb" }
+  # watch(%r{^lib/(.+)\.rb$})                               { |m| "test/lib/#{m[1]}_test.rb" }
+  # watch(%r{^test/.+_test\.rb$})
+  # watch(%r{^test/test_helper\.rb$}) { 'test' }
+
+  # Rails < 4
+  # watch(%r{^app/controllers/(.*)\.rb$}) { |m| "test/functional/#{m[1]}_test.rb" }
+  # watch(%r{^app/helpers/(.*)\.rb$})     { |m| "test/helpers/#{m[1]}_test.rb" }
+  # watch(%r{^app/models/(.*)\.rb$})      { |m| "test/unit/#{m[1]}_test.rb" }
+end
+
+guard :rubocop do
+  watch(%r{.+\.rb$})
+  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+end

data/README.md

@@ -1,12 +1,14 @@
 [![Build Status](https://travis-ci.org/EvidentSecurity/esp_sdk.svg?branch=master)](https://travis-ci.org/EvidentSecurity/esp_sdk)
 [![Code Climate](https://codeclimate.com/repos/546a526f6956800d2900e3fb/badges/841000b5295e533401c3/gpa.svg)](https://codeclimate.com/repos/546a526f6956800d2900e3fb/feed)
-[![Test Coverage](https://codeclimate.com/repos/546a526f6956800d2900e3fb/badges/841000b5295e533401c3/coverage.svg)](https://codeclimate.com/repos/546a526f6956800d2900e3fb/feed)
+[![Coverage Status](https://coveralls.io/repos/EvidentSecurity/esp_sdk/badge.svg)](https://coveralls.io/r/EvidentSecurity/esp_sdk)
 [![Gem Version](https://badge.fury.io/rb/esp_sdk.svg)](http://badge.fury.io/rb/esp_sdk)
 
-# EspSdk
+# Evident Security Platform SDK
 
 A Ruby interface for calling the [Evident.io](https://www.evident.io) API.
 
+This Readme is for the V2 version of the ESP SDK.  For V1 information, see the [**V1 WIKI**](https://github.com/EvidentSecurity/esp_sdk/wiki).
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -15,15 +17,238 @@ Add this line to your application's Gemfile:
 
 And then execute:
 
-    $ bundle
+     bundle
 
 Or install it yourself as:
 
-    $ gem install esp_sdk
+     gem install esp_sdk
+
+# Configuration
+
+## Set your HMAC security keys:
+
+You must set your access_key_id and your secret_access_key.  
+You can set these directly:
+
+```ruby
+ESP.access_key_id = <your key>
+ESP.secret_access_key = <your secret key>
+```
+      
+or with environment variables:
+
+```ruby
+ENV['ESP_ACCESS_KEY_ID'] = <you key>
+ENV['ESP_SECRET_ACCESS_KEY'] = <your secret key>
+```
+      
+or, if in a Rails application, you can use the configure block in an initializer:
+
+```ruby
+ESP.configure do |config|
+  config.access_key_id = <your key>
+  config.secret_access_key = <your secret key>
+end
+```
+      
+Get your HMAC keys from the Evident.io website, [esp.evident.io](https://esp.evident.io/settings/api_keys)
+
+## Appliance Users
+
+Users of Evident.io's AWS marketplace appliance will need to set the host for their appliance instance.
+You can set this directly:
+
+```ruby
+ESP.host = <host for appliance instance>
+```
+      
+or, if in a Rails application, you can use the configure block in an initializer:
+
+```ruby
+ESP.configure do |config|
+  config.host = <host for appliance instance>
+end
+```
+
+Alternatively, the site can also be set with an environment variable.
+
+
+```
+export ESP_HOST=<host for appliance instance>
+```
 
 # Usage
 
-See the [**WIKI**](https://github.com/EvidentSecurity/esp_sdk/wiki) for information on using the SDK.
+## Everything is an Object
+
+The Evident.io SDK uses Active Resource, so the DSL acts very much like Active Record providing by default, the standard CRUD actions
+`find`, `all`, `create`, `update`, `destroy`, only instead of a database as the data store, it makes calls to the Evident.io API.  Not all
+methods are available for all ESP objects.  See the [documentation](http://www.rubydoc.info/gems/esp_sdk) to see all the methods 
+available for each object.
+So, for instance, to get a report by ID:
+
+```ruby
+espsdk:003:0> report = ESP::Report.find(234)
+```
+    
+And to get the alerts for that report:
+
+```ruby
+espsdk:003:0> alerts = report.alerts
+```
+
+For objects that are creatable, updatable, and destroyable, you make the exact same calls you would expect to use with Active Record.
+
+```ruby
+espsdk:003:0> team = ESP::Team.create(name: 'MyTeam', organization_id: 452, sub_organization_id: 599)
+    
+espsdk:003:0> team.name = 'NewName'
+espsdk:003:0> team.save
+    
+espsdk:003:0> team.destroy
+```
+    
+Use the `attributes` method to get a list of all available attributes that each object has.
+
+```ruby
+espsdk:003:0> team = ESP::Team.find(1)
+espsdk:004:0> team.attributes
+# => {
+# =>                       "id" => "1",
+# =>                     "type" => "teams",
+# =>            "relationships" => #<ESP::Team::Relationships:0x007fdf1b451710 @attributes={"sub_organization"=>#<ESP::SubOrganization:0x007fdf1b450d60 @attributes={"data"=>#<ESP::SubOrganization::Data:0x007fdf1b450978 @attributes={"id"=>"1", "type"=>"sub_organizations"}, @prefix_options={}, @persisted=true>, "links"=>#<ESP::SubOrganization::Links:0x007fdf1b4503b0 @attributes={"related"=>"http://localhost:3000/api/v2/sub_organizations/1.json"}, @prefix_options={}, @persisted=true>}, @prefix_options={}, @persisted=true>, "organization"=>#<ESP::Organization:0x007fdf1b45bbc0 @attributes={"data"=>#<ESP::Organization::Data:0x007fdf1b45b7d8 @attributes={"id"=>"1", "type"=>"organizations"}, @prefix_options={}, @persisted=true>, "links"=>#<ESP::Organization::Links:0x007fdf1b45b210 @attributes={"related"=>"http://localhost:3000/api/v2/organizations/1.json"}, @prefix_options={}, @persisted=true>}, @prefix_options={}, @persisted=true>, "external_accounts"=>#<ESP::Team::Relationships::ExternalAccounts:0x007fdf1b45a040 @attributes={"data"=>[#<ESP::Team::Relationships::ExternalAccounts::Datum:0x007fdf1b458830 @attributes={"id"=>"1", "type"=>"external_accounts"}, @prefix_options={}, @persisted=true>], "links"=>#<ESP::Team::Links:0x007fdf1b463e38 @attributes={"related"=>"http://localhost:3000/api/v2/external_accounts.json"}, @prefix_options={}, @persisted=true>}, @prefix_options={}, @persisted=true>}, @prefix_options={}, @persisted=true>,
+# =>                     "name" => "Default Team",
+# =>               "created_at" => "2015-09-23T14:37:48.000Z",
+# =>               "updated_at" => "2015-09-23T14:37:48.000Z",
+# =>      "sub_organization_id" => "1",
+# =>          "organization_id" => "1",
+# =>     "external_account_ids" => [
+# =>         [0] "1"
+# =>     ]
+# => }
+```
+    
+## Errors
+Active Resource objects have an errors collection, just like Active Record objects.  If the API call returns a non fatal response, like 
+validation issues, you can check the errors object to see what went wrong.
+
+```ruby
+espsdk:003:0> t = ESP::Team.create(name: '')
+espsdk:003:0> t.errors
+# => {
+# =>     :base => [
+# =>         [0] "Organization can't be blank",
+# =>         [1] "Sub organization can't be blank"
+# =>     ],
+# =>     :name => [
+# =>         [0] "can't be blank"
+# =>     ]
+# => }
+```
+    
+The errors will be in the :base key rather than the corresponding attribute key, since we have not defined a schema for the objects
+in order to stay more loosely coupled to the API.
+
+```ruby
+espsdk:003:0> t.errors.full_messages
+# => [
+# =>     [0] "Organization can't be blank",
+# =>     [1] "Sub organization can't be blank",
+# =>     [2] "Name can't be blank"
+# => ]
+```
+
+When an error is thrown, you can rescue the error and check the error message:
+
+```ruby
+espsdk:003:0> c = ESP::CustomSignature.find(435)
+espsdk:003:0> c.run!(external_account_id: 999)
+# =>  ActiveResource::ResourceInvalid: Failed.  Response code = 422.  Response message = Couldn't find ExternalAccount. 
+# =>    from /Users/kevintyll/evident/esp_sdk/lib/esp/resources/custom_signature.rb:23:in `run!'
+
+begin
+  c.run!(external_account_id: 999)
+rescue ActiveResource::ResourceInvalid => e
+  puts e.message
+end
+# => Failed.  Response code = 422.  Response message = Couldn't find ExternalAccount.
+```
+    
+All non get requests have a corresponding `!` version of the method.  These methods will throw an error rather than swallow
+the error and return an object with the errors object populated. For example, the `run` and `run!` methods on CustomSignature.
+
+## Pagination
+Evident.io API endpoints that return a collection of objects allows for paging and only returns a limited number of items at a time.
+The Evident.io SDK returns an ESP::PaginatedCollection object that provides methods for paginating through the collection. 
+The methods with a `!` suffix update the object, methods without the `!` suffix return a new page object preserving the
+original object.
+
+```ruby
+espsdk:004:0> alerts = ESP::Alert.for_report(345)
+espsdk:004:0> alerts.current_page_number # => "1"
+espsdk:004:0> page2 = alerts.next_page
+espsdk:004:0> alerts.current_page_number # => "1"
+espsdk:004:0> page2.current_page_number # => "2"
+espsdk:004:0> page2.previous_page!
+espsdk:004:0> page2.current_page_number # => "1"
+espsdk:004:0> alerts.last_page!
+espsdk:004:0> alerts.current_page_number # => "25"
+espsdk:004:0> page4 = alerts.page(4)
+espsdk:004:0> alerts.current_page_number # => "25"
+espsdk:004:0> page4.current_page_number # => "4"
+```
+    
+## Associated Objects
+Most of the objects in the Evident.io SDK have a corresponding API call associated with it.  That means if you call an object's
+association, then that will make another API call.  For example:
+
+```ruby
+espsdk:004:0> external_account = ESP::ExternalAccount.find(3)
+espsdk:004:0> organization = external_account.organization
+espsdk:004:0> sub_organization = external_account.sub_organization
+espsdk:004:0> team = external_account.team
+```
+
+The above code will make 4 calls to the Evident.io API.  1 each for the external account, organization, sub_organization and team.
+The [JSON API Specification](http://jsonapi.org/format/#fetching-includes), which the Evident.io API tries to follow, provides
+a means for returning nested objects in a single call.  With the SDK, that can be done by providing a comma separated string
+of the relations wanted in an +include+ option.
+
+```ruby
+espsdk:004:0> external_account = ESP::ExternalAccount.find(3, include: 'organization,sub_orgnanization,team')
+```
+
+With that call, organization, sub_organization and team will all come back in the response, and calling, `external_account.organization`,
+`external_account.sub_organization` and `external_account.team`, will not make another API call.  Most objects' find method accepts the
++include+ option.
+    
+See the [**Documentation**](http://www.rubydoc.info/gems/esp_sdk/ESP/ActiveResource/PaginatedCollection.html) for all the pagination methods available.
+
+## Available Objects
+* [ESP::Alert](http://www.rubydoc.info/gems/esp_sdk/ESP/Alert.html)
+* [ESP::CloudTrailEvent](http://www.rubydoc.info/gems/esp_sdk/ESP/CloudTrailEvent.html)
+* [ESP::ContactRequest](http://www.rubydoc.info/gems/esp_sdk/ESP/ContactRequest.html)
+* [ESP::CustomSignature](http://www.rubydoc.info/gems/esp_sdk/ESP/CustomSignature.html)
+* [ESP::Dashboard](http://www.rubydoc.info/gems/esp_sdk/ESP/Dashboard.html)
+* [ESP::ExternalAccount](http://www.rubydoc.info/gems/esp_sdk/ESP/ExternalAccount.html)
+* [ESP::Organization](http://www.rubydoc.info/gems/esp_sdk/ESP/Organization.html)
+* [ESP::Region](http://www.rubydoc.info/gems/esp_sdk/ESP/Region.html)
+* [ESP::Report](http://www.rubydoc.info/gems/esp_sdk/ESP/Report.html)
+* [ESP::Service](http://www.rubydoc.info/gems/esp_sdk/ESP/Service.html)
+* [ESP::Signature](http://www.rubydoc.info/gems/esp_sdk/ESP/Signature.html)
+* [ESP::Stat](http://www.rubydoc.info/gems/esp_sdk/ESP/Stat.html)
+* [ESP::SubOrganization](http://www.rubydoc.info/gems/esp_sdk/ESP/SubOrganization.html)
+* [ESP::Suppression](http://www.rubydoc.info/gems/esp_sdk/ESP/Suppression.html)
+* [ESP::Suppression::Region](http://www.rubydoc.info/gems/esp_sdk/ESP/Suppression::Region.html)
+* [ESP::Suppression::Signature](http://www.rubydoc.info/gems/esp_sdk/ESP/Suppression::Signature.html)
+* [ESP::Suppression::UniqueIdentifier](http://www.rubydoc.info/gems/esp_sdk/ESP/Suppression::UniqueIdentifier.html)
+* [ESP::Tag](http://www.rubydoc.info/gems/esp_sdk/ESP/Tag.html)
+* [ESP::Team](http://www.rubydoc.info/gems/esp_sdk/ESP/Team.html)
+* [ESP::User](http://www.rubydoc.info/gems/esp_sdk/ESP/User.html)
+
+# Console
+The Evident.io SDK gem also provides an IRB console you can use if not using it in a Rails app.  Run it with `bin/esp_console`
+
 
 ## Contributing