smartsheet 1.0.0 → 1.1.0

data/README.md

@@ -1,141 +1,214 @@
-# Smartsheet Ruby SDK [![Build Status](https://travis-ci.org/smartsheet-platform/smartsheet-ruby-sdk.svg?branch=master)](https://travis-ci.org/smartsheet-platform/smartsheet-ruby-sdk) [![Coverage Status](https://coveralls.io/repos/github/smartsheet-platform/smartsheet-ruby-sdk/badge.svg?branch=master)](https://coveralls.io/github/smartsheet-platform/smartsheet-ruby-sdk?branch=master) [![Gem Version](https://badge.fury.io/rb/smartsheet.svg)](https://badge.fury.io/rb/smartsheet)
-
-This is an SDK to simplify connecting to the [Smartsheet API](http://www.smartsheet.com/developers/api-documentation) from Ruby applications.
-
-## System Requirements
-
-The SDK supports Ruby versions 2.2 or later.
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'smartsheet', '>= 1.0.0'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install smartsheet --pre
-
-## Documentation
-
-The Smartsheet API documentation with corresponding SDK example code can be found [here](http://www.smartsheet.com/developers/api-documentation).
-
-## Example Usage
-
-To call the API, you must have an access token, which looks something like this example: ll352u9jujauoqz4gstvsae05. You can find the access token in the UI at Account > Personal Settings > API Access. 
-
-The following is a brief sample that shows you how to:
-
-* Initialize the client
-* List all sheets
-* Load one sheet
-
-```ruby
-require 'smartsheet'
-
-# Initialize the client
-smartsheet_client = Smartsheet::Client.new(token: 'll352u9jujauoqz4gstvsae05')
-
-# The `smartsheet_client` variable now contains access to all of the APIs
-
-begin
-  # List all sheets
-  sheets = smartsheet_client.sheets.list
-
-  # Default to first sheet
-  sheet_id = sheets[:data][0][:id]
-
-  # Load the entire sheet
-  puts smartsheet_client.sheets.get(sheet_id: sheet_id)
-rescue Smartsheet::ApiError => e
-  puts "Error Code: #{e.error_code}"
-  puts "Message: #{e.message}"
-  puts "Ref Id: #{e.ref_id}"
-end
-```
-
-See the [read-write-sheet](https://github.com/smartsheet-samples/ruby-read-write-sheet) example to see a more robust use case in action.
-
-## Basic Configuration
-
-When creating the client object, pass an object with any of the following properties to tune its behavior.
-
-* `max_retry_time` - The maximum time in seconds to retry intermittent errors. (Defaults to 15 seconds.)
-
-## Advanced Configuration Options
-### Logging Configuration
-
-Smartsheet expects a standard Ruby logger.  For example, to enable console logging of warnings and above, make a call such as the following:
-
-```ruby
-logger = Logger.new(STDOUT)
-logger.level = Logger::WARN
-smartsheet = Smartsheet::Client.new(logger: logger)
-```
-
-Supported log levels are as follows:
-
-|Level          |What is logged                   |
-|---------------|---------------------------------|
-|`Logger::ERROR`|Failures only                    |
-|`Logger::WARN` |Failures and retries             |
-|`Logger::INFO` |Each call's URL and response code|
-|`Logger::DEBUG`|Full headers and payloads        |
-
-By default, payloads are truncated to 1024 characters.  To display full payloads, pass the `log_full_body` named flag to the `Smartsheet::Client` with the value true:
-
-```ruby
-smartsheet = Smartsheet::Client.new(logger: logger, log_full_body: true)
-```
-
-### Retry Configuration
-
-For additional customization, you can specify a `backoff_method` function.  This function is called with two arguments:
-
-* The first accepts the index of the retry being attempted (0 for the first retry, 1 for the second, etc.)
-* The second accepts the Error Object that caused the retry.
-
-The function must return the number of seconds to wait before making the subsequent retry call, or the symbol `:stop` if no more retries should be made.
-
-The default implementation performs exponential backoff with jitter.
-
-### JSON Output
-
-* `json_output` - A flag indicating if data should be returned as a JSON string. Defaults to Hash output when not specified.
-
-### Assume User
-
-* `assume_user` - Allows an admin to act on behalf of, or impersonate, the user to make API calls. The email address should NOT be URI encoded.
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests, with code coverage provided automatically by the Coveralls gem. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`.
-
-## Contributing
-
-If you would like to contribute a change to the SDK, please fork a branch and then submit a pull request.
-[More info here.](https://help.github.com/articles/using-pull-requests)
-
-## Support
-
-If you have any questions or issues with this SDK please post on [Stack Overflow using the tag "smartsheet-api"](http://stackoverflow.com/questions/tagged/smartsheet-api) or contact us directly at api@smartsheet.com.
-
-## Release Notes
-
-Each specific release is available for download via [GitHub](https://github.com/smartsheet-platform/smartsheet-ruby-sdk/tags).
-
-**v1.0.0 (Nov 2017)**
-Full release
-
-**v1.0.0.beta (October 2017)**
-Beta release of the Smartsheet SDK for Ruby
-
-*Note*: Minor changes that result in a patch version increment in RubyGems (such as updates to the README) will not be tagged as a Release in GitHub.
+# Smartsheet Ruby SDK [![Build Status](https://travis-ci.org/smartsheet-platform/smartsheet-ruby-sdk.svg?branch=master)](https://travis-ci.org/smartsheet-platform/smartsheet-ruby-sdk) [![Coverage Status](https://coveralls.io/repos/github/smartsheet-platform/smartsheet-ruby-sdk/badge.svg?branch=master)](https://coveralls.io/github/smartsheet-platform/smartsheet-ruby-sdk?branch=master) [![Gem Version](https://badge.fury.io/rb/smartsheet.svg)](https://badge.fury.io/rb/smartsheet)
+
+This is an SDK to simplify connecting to the [Smartsheet API](http://www.smartsheet.com/developers/api-documentation) from Ruby applications.
+
+## System Requirements
+
+The SDK supports Ruby versions 2.2 or later.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'smartsheet', '>= 1.0.0'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install smartsheet
+
+## Documentation
+
+The Smartsheet API documentation with corresponding SDK example code can be found [here](http://www.smartsheet.com/developers/api-documentation).
+
+The generated SDK RubyDoc is available [here](http://www.rubydoc.info/gems/smartsheet/Smartsheet).
+
+## Example Usage
+
+To call the API, you must have an access token, which looks something like this example: `ll352u9jujauoqz4gstvsae05`. You can find the access token in the UI at Account > Personal Settings > API Access.
+
+The following is a brief sample that shows you how to:
+
+* Initialize the client
+* List all sheets
+* Load one sheet
+
+```ruby
+require 'smartsheet'
+
+# Initialize the client - use your access token here
+smartsheet_client = Smartsheet::Client.new(token: 'll352u9jujauoqz4gstvsae05')
+# The `smartsheet_client` variable now contains access to all of the APIs
+
+begin
+  # List all sheets
+  sheets = smartsheet_client.sheets.list
+
+  # Select first sheet
+  sheet_id = sheets[:data][0][:id]
+
+  # Load the entire sheet
+  puts "Loading sheet id #{sheet_id}"
+  sheet = smartsheet_client.sheets.get(sheet_id: sheet_id)
+  puts "Loaded #{sheet[:total_row_count]} rows from sheet '#{sheet[:name]}'"
+
+rescue Smartsheet::ApiError => e
+  puts "Error Code: #{e.error_code}"
+  puts "Message: #{e.message}"
+  puts "Ref Id: #{e.ref_id}"
+end
+```
+
+See the [read-write-sheet](https://github.com/smartsheet-samples/ruby-read-write-sheet) example to see a more robust use case in action.
+
+## Basic Configuration
+
+When creating the client object, pass an object with any of the following properties to tune its behavior.
+
+* `token` - Your smartsheet API access token. If you omit this property (or pass an empty string) then the access token will be read from the system environment variable `SMARTSHEET_ACCESS_TOKEN`.
+
+* `max_retry_time` - The maximum time in seconds to retry intermittent errors. (Defaults to 15 seconds.)
+
+* `base_url` - By default, the SDK connects to the production API URL. Provide a custom base URL to connect to other environments.
+
+## Advanced Configuration Options
+### Logging Configuration
+
+Smartsheet expects a standard Ruby logger.  For example, to enable console logging of warnings and above, make a call such as the following:
+
+```ruby
+logger = Logger.new(STDOUT)
+logger.level = Logger::INFO
+smartsheet = Smartsheet::Client.new(logger: logger)
+```
+
+Supported log levels are as follows:
+
+|Level          |What is logged                   |
+|---------------|---------------------------------|
+|`Logger::ERROR`|Failures only                    |
+|`Logger::WARN` |Failures and retries             |
+|`Logger::INFO` |Each call's URL and response code|
+|`Logger::DEBUG`|Full headers and payloads        |
+
+By default, payloads are truncated to 1024 characters.  To display full payloads, pass the `log_full_body` named flag to the `Smartsheet::Client` with the value true:
+
+```ruby
+smartsheet = Smartsheet::Client.new(logger: logger, log_full_body: true)
+```
+
+### Retry Configuration
+
+For additional customization, you can specify a `backoff_method` function.  This function is called with two arguments:
+
+* The first accepts the index of the retry being attempted (0 for the first retry, 1 for the second, etc.)
+* The second accepts the Error Object that caused the retry.
+
+The function must return the number of seconds to wait before making the subsequent retry call, or the symbol `:stop` if no more retries should be made.
+
+The default implementation performs exponential backoff with jitter.
+
+### JSON Input and Output
+* `json_output` - A flag indicating if data should be returned as a JSON string. 
+
+    By default, the Ruby SDK converts the raw JSON API response (with camelCase properties) to a Ruby hash with snake_case properties. If you prefer to receive results as the original JSON string, initialize the client with `json_output: true`.
+
+    Regardless of this setting, the SDK will accept `body` parameters as a hash or JSON, and in either camelCase or snake_case.
+
+### Assume User
+
+* `assume_user` - Allows an admin to act on behalf of, or impersonate, the user to make API calls. The email address should NOT be URI encoded.
+
+### User Agent
+
+* `user_agent` - A custom app name to add to the user agent header; this helps Smartsheet diagnose any issues you may have while using the SDK.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Running the Tests
+#### All
+1. Run `rake test`. Note, the mock API tests will fail unless the mock server is running. See [Mock API Tests](#mock-api-tests)
+
+#### Unit Tests
+1. Run `rake test:units`
+
+#### Mock API Tests
+1. Clone the [Smartsheet SDK tests](https://github.com/smartsheet-platform/smartsheet-sdk-tests) repo and follow the instructions from the README to start the mock server
+2. Run `rake test:mock_api`
+
+## Passthrough Option
+
+If there is an API Feature that is not yet supported by the Ruby SDK, there is a passthrough option that allows you to call arbitrary API endpoints.
+
+To invoke the passthrough, your code can call one of the following three methods:
+
+`response = smartsheet.request(method:, url_path:, body:, params:, header_overrides:)`
+
+`response = smartsheet.request_with_file(method:, url_path:, file:, file_length:, filename:, content_type:, params:, header_overrides:)`
+
+`response = smartsheet.request_with_file_from_path(method:, url_path:, path:, filename:, content_type:, params:, header_overrides:)`
+
+* `method`: The method to invoke, one of `:get`, `:post`, `:put`, or `:delete`
+* `url_path`: The specific API endpoint you wish to invoke. The client object base URL gets prepended to the caller’s endpoint URL argument.  For example, passing a `url_path` of `sheets/1` to a standard client would give a URL like `https://api.smartsheet.com/2.0/sheets/1`
+* `body`: An optional hash of data to be passed as a JSON request body
+* `file`: An opened `File` object to read as the request body, generally for file attachment endpoints
+* `path`: The path of a file to be read as the request body, generally for file attachment endpoints
+* `file_length`: The length of a file body in octets
+* `filename`: The name of a file body
+* `content_type`: The MIME type of a file body
+* `params`: An optional hash of query parameters
+* `header_overrides`: An optional hash of HTTP header overrides
+
+All calls to passthrough methods return a JSON result, converted to a hash using symbol keys, in the same manner as the rest of the SDK. For example, after a `PUT` operation, the API's result message could be contained in `response[:message]`. If you prefer raw JSON instead of a hash, create a client with `json_output` configured; see client documentation above for more info.
+
+### Passthrough Example
+
+The following example shows how to POST data to `https://api.smartsheet.com/2.0/sheets` using the passthrough method and a hash:
+
+```ruby
+payload = {
+  name: 'my new sheet',
+  columns: [
+    {
+      title: 'Favorite',
+      type: 'CHECKBOX',
+      symbol: 'STAR'
+    },
+    {
+      title: 'Primary Column',
+      primary: true,
+      type: 'TEXT_NUMBER'
+    }
+  ]
+}
+
+response = smartsheet.request(
+  method: :post,
+  url_path: 'sheets',
+  body: payload
+)
+```
+
+## Contributing
+
+If you would like to contribute a change to the SDK, please fork a branch and then submit a pull request.
+[More info here.](https://help.github.com/articles/using-pull-requests)
+
+## Support
+
+If you have any questions or issues with this SDK please post on [Stack Overflow using the tag "smartsheet-api"](http://stackoverflow.com/questions/tagged/smartsheet-api) or contact us directly at api@smartsheet.com.
+
+## Release Notes
+
+Each specific release is available for download via [GitHub](https://github.com/smartsheet-platform/smartsheet-ruby-sdk/tags).  Detailed release notes are available in [CHANGELOG.md].
+
+*Note*: Minor changes that result in a patch version increment in RubyGems (such as updates to the README) will not be tagged as a Release in GitHub.

data/Rakefile

@@ -1,23 +1,29 @@
-require 'bundler/gem_tasks'
-require 'rake/testtask'
-require 'rubycritic/rake_task'
-
-
-Rake::TestTask.new do |t|
-  t.libs << 'test'
-  t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
-end
-
-namespace :test do
-  Rake::TestTask.new(:units) do |t|
-    t.libs << 'test'
-    t.pattern = 'test/unit/**/*_test.rb'
-    t.verbose = true
-  end
-end
-
-
-RubyCritic::RakeTask.new
-
-task default: :test
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubycritic/rake_task'
+
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+namespace :test do
+  Rake::TestTask.new(:units) do |t|
+    t.libs << 'test'
+    t.pattern = 'test/unit/**/*_test.rb'
+    t.verbose = true
+  end
+
+  Rake::TestTask.new(:mock_api) do |t|
+    t.libs << 'test'
+    t.pattern = 'test/mock_api/**/*_test.rb'
+    t.verbose = true
+  end
+end
+
+
+RubyCritic::RakeTask.new
+
+task default: :'test:units'

data/bin/console

@@ -1,14 +1,14 @@
-#!/usr/bin/env ruby
-
-require 'bundler/setup'
-require 'smartsheet/client'
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'irb'
-IRB.start(__FILE__)
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'smartsheet/client'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -1,8 +1,8 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here