bubbles-rest-client 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa7191e00b0fa6396be519250117e31e924c258f368cf7d1c9e02697234bcab0
-  data.tar.gz: e989353ef2ef2fc4cb07014fb3b2a9a0dfce0bf778b820582c98c13502c1de1d
+  metadata.gz: 57f1034be17b96ea4181b77b4ff472b1e10c8b435d3569180a2c2e008286c573
+  data.tar.gz: 1206b4f733335dfc41d4fa02cb6c171840187c105f2967afcb10d62939015f2c
 SHA512:
-  metadata.gz: 046af961bf1da02e71a2193cfad8cd048084dc021e6786bfc1df753d54730284b4d3bd309f383b8b9456e4628a5c21a24beccbbddc25977c6b93c40485b1bfe8
-  data.tar.gz: 579c841ef7eb221a3d86e3e0ef13e77e77fb08a9ecacf70847f4a5c38509b7de2541507b9d45d05b26eb98c3e93dfcc61b229cbd8b8efba70c8b44336a361530
+  metadata.gz: 050ecf0c162ceec1bbbfac219db53b2e33ec509545e6574f67b6a9f685cf10706f9ea314c9b188d96a23c0109ef4538246d5fc7fb4cc5fafb1ccf200ffdcd3cb
+  data.tar.gz: 152a955fc1788a341c2de601b5d8d6eff7a4263e1d9965f64d7f3943fb2d7f218f092716cd13117a873a2422d0f0efac84be72e90aff9c2147bf02b87f44b8fd

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.6.1
+script: bundle exec rake spec
+branches:
+  only:
+    - master

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,77 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers of Bubbles pledge to making participation in our
+project and our community a harassment-free experience for everyone,
+regardless of age, body size, disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education,
+socio-economic status, nationality, personal appearance, race, religion,
+or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community and users
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+ advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+ address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting Scott Johnson, our project lead, at jaywir3@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project leadership
+team is obligated to maintain confidentiality with regard to the reporter of an
+incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

data/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to Bubbles
+
+## Introduction
+First off, thanks for looking to contribute to Bubbles! We need people like you
+to help us make the best quality product we possibly can. Regardless of whether
+you're a developer, a designer, a technical writer, a student, or even someone
+just interested in learning more about open source and how to contribute, you're
+welcome here.
+
+## Code of Conduct
+Please take a look at our contributor [Code of Conduct](CODE_OF_CONDUCT.md). We
+take harassment and non-inclusive behavior very seriously and will not tolerate
+bullying in any form.
+
+## Development Process
+Our development process works as follows:
+
+1. Fork this repository to your own local Github account.
+2. Clone your local version of the repository: `git clone git@github.com:<username>/bubbles`.
+3. Create a branch on your local repository: `git checkout -b <username>/#<issue>-<short-description>`.
+4. Make any changes you see fit to fix the issue or add your work.
+5. Verify that tests pass: `bundle install && rake spec`.
+6. If you're adding a new feature, make sure to add tests for the feature.
+7. Commit your changes and push to your fork of the repository.
+8. Submit a pull request to the `master` branch of the original repository.
+9. You will receive a review within 7 days, at which time, you may need to make
+   modifications to your code, or your contribution might be accepted as-is.
+
+## Good First Issues
+You can take a look at our [good first issues](https://github.com/FoamFactory/bubbles/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+to check out some issues that might be a good starting point for you.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bubbles-rest-client (0.4.0)
+    bubbles-rest-client (0.5.0)
       addressable (~> 2.5)
       rest-client (~> 2.0)
 
@@ -33,6 +33,7 @@ GEM
       minitest (>= 5.0)
       ruby-progressbar
     netrc (0.11.0)
+    os (1.0.1)
     public_suffix (3.0.3)
     rake (10.5.0)
     rest-client (2.1.0)
@@ -77,6 +78,7 @@ DEPENDENCIES
   bundler (~> 2.0.0)
   minitest (~> 5.0)
   minitest-reporters (~> 1.1)
+  os
   rake (~> 10.0)
   rspec (~> 3.8)
   simplecov (~> 0.16)

data/README.md

@@ -1,4 +1,6 @@
 # bubbles
+[![Build Status](https://travis-ci.org/FoamFactory/bubbles.svg?branch=master)](https://travis-ci.org/FoamFactory/bubbles)
+
 A gem for easily defining client REST interfaces in ruby
 
 ## Project Goals
@@ -28,9 +30,7 @@ _bubbles_ is a Gem that seeks to provide this same behavior.
 
 Currently, bubbles has a number of limitations that make it likely not suitable for use in a production environment. Each of these is tracked by an issue on our [issues page](https://github.com/FoamFactory/bubbles/issues).
 
-  - Passing an API key with a request is restricted to using `X-Api-Key` as a header key (#10).
-  - Some request methods (specifically `DELETE`) do not currently allow unauthenticated access. In other words, it is not possible to perform a `DELETE` request on your API without passing an authorization token. (#16)
-  - Not all possible combinations of `has_uri_params`, `authenticated`, and `api_key_required` are tested. In some cases, such as with `GET` requests, there aren't any tests for possible configuration cases that might cause issues when combined. (#12)
+  - Some request methods (specifically `DELETE`) do not currently allow unauthenticated access. In other words, it is not possible to perform a `DELETE` request on your API without passing an authorization token. (FoamFactory/bubbles#16)
 
 If you're interested in working on any of the issues above, please feel free to submit a pull request and a member of our team will review that pull request within a couple of days.
 
@@ -52,7 +52,7 @@ Bubbles.configure do |config|
     }
   ]
 
-  config.local_environment = {
+  config.environment = {
     :scheme => 'http',
     :host => '0.0.0.0',
     :port => '1234'
@@ -60,12 +60,11 @@ Bubbles.configure do |config|
 end
 ```
 
-The `config.endpoints` section is where you configure which endpoints you want to support. The `config.local_environment` defines an environment, or remote configuration, for accessing the endpoint on a specific remote destination.
+The `config.endpoints` section is where you configure which endpoints you want to support. The `config.environment` defines an environment, or remote configuration, for accessing the endpoint on a specific remote destination.
 
 Now, you can use this endpoint with:
 ```ruby
 require 'bubbles'
-
 ...
 
 def version
@@ -73,7 +72,7 @@ def version
 
   # The following will make a GET request to
   # http://0.0.0.0:1234/version and return the result.
-  result = resources.local_environment.version
+  result = resources.environment.version
 
   puts(result)
 end
@@ -83,13 +82,15 @@ end
 There are currently two parts to a bubbles configuration: the _environments_ and the _endpoints_. Bubbles is configured in a _bubbles configuration block_:
 ```ruby
 Bubbles.configure do |config|
-...
+  # You can add configuration for Bubbles here using config.endpoints and config.environment
 end
 ```
 
 This configuration block can be run at any time, but is typically set up in the initializer section of an app's startup. If desired, configuration can happen separately. That is, you can initialize environments within your initializer file and then initialize endpoints within another section of the application. Just note that when endpoints are defined, it overwrites _all_ endpoints of a configuration, not just the ones you choose to change.
 
 ### Environments
+> :construction: Environment names used to be hardcoded into Bubbles. You can now access the current environment using `Bubbles::Resources.new.environment`. This section is left in the documentation for future reference, as we will eventually be adding back named environments (see FoamFactory/bubbles#23 for tracking information).
+
 Three environments are currently available to be set up within bubbles. These are:
   - `local_environment` : Designed to be used for a local API for development testing.
   - `staging_environment` : Designed to be used for a remote API for second-stage testing or production-like deployment.
@@ -104,27 +105,30 @@ Environments are configured as part of the _bubbles configuration block_ and can
   - `host`: A domain name or IP address for the remote host to access for the environment.  Defaults to `127.0.0.1`.
   - `port`: The port to use to access the remote host. Defaults to `1234`.
   - `api_key`: The API key to send along with requests for a given environment, if an API key is required. This is optional, and defaults to `nil`.
+  - `headers`: A `Hash` of key-value pairs that contain additional headers to pass to every call to this endpoint. Defaults to `{}`.
 
 You can configure all three environments at once in the _bubbles configuration block_:
 ```ruby
 Bubbles.configure do |config|
-  config.local_environment = {
+  config.environment = {
     :scheme => 'http',
     :host => '0.0.0.0',
     :port => '1234'
   }
 
-  config.staging_environment = {
-    :scheme => 'http',
-    :host => 'stage.api.foamfactory.com',
-    :port => '80'
-  }
-
-  config.production_environment = {
-    :scheme => 'https',
-    :host => 'api.foamfactory.com',
-    :port => '443'
-  }
+  # Note: This is deprecated for the time being. See (FoamFactory/bubbles/#23).
+  # config.staging_environment = {
+  #   :scheme => 'http',
+  #   :host => 'stage.api.foamfactory.com',
+  #   :port => '80'
+  # }
+
+  # Note: This is deprecated for the time being. See (FoamFactory/bubbles/#23).
+  # config.production_environment = {
+  #   :scheme => 'https',
+  #   :host => 'api.foamfactory.com',
+  #   :port => '443'
+  # }
 end
 ```
 
@@ -164,14 +168,178 @@ Each _endpoint_ object can have the following attributes:
 | `api_key_required` | Whether or not an API key is required. If `true`, a parameter will be added to the method created to execute the REST API call named `api_key`. The value of this parameter will be set as the value of the `X-Api-Key` header when making the REST API call. | No | `false` |
 | `return_type` | Must be one of: `[full_response, body_as_object, body_as_string]`. This specifies what type of response is expected from the `Endpoint`. A value of `full_response` will return the full `RestClient::Response` object to the client. A value of `body_as_string` will return the `RestClient::Response.body` value as a `String`. A value of `body_as_object` will take the `RestClient::Response.body` parameter and parse it as an `OpenStruct` object, and return the result of this parsing operation. | No | `body_as_string` |
 | `encode_authorization` | Whether the `data` passed as part of the request should be re-encoded as an `Authorization: Basic` header (and Base64 encoded). Typically, this is only used for initial username/password authentication. | No | `false` |
+| `headers` | A `Hash` of key-value pairs specifying additional headers (the `key` specifies the name of the header, and the `value` specifies the value) that should be passed with each call to this `Endpoint`. Defaults to `{}`.
 
 ### Examples
+These examples are taken almost directly from our [test suite](https://github.com/FoamFactory/bubbles/blob/master/spec/bubbles/resources_spec.rb). For more detailed examples, please refer to our specifications located in the `/spec` directory.
+
 #### GET the version of the software (unauthenticated, no API key required)
+**Configuration**:
+
+```ruby
+require 'bubbles'
+
+Bubbles.configure do |config|
+  config.endpoints = [
+    {
+      :method => :get,
+      :location => :version,
+      :authenticated => false,
+      :api_key_required => false,
+      :return_type => :body_as_object
+    }
+  ]
+
+  config.environment = {
+    :scheme => 'http',
+    :host => '0.0.0.0',
+    :port => '1234'
+  }
+end
+```
+
+**Usage**:
+```ruby
+it 'should return an object containing the version information from the API' do
+  resources = Bubbles::Resources.new
+  environment = resources.environment
+
+  response = environment.version
+  expect(response).to_not be_nil
+  expect(response.name).to eq('My Sweet API')
+  expect(response.versionName).to eq('0.0.1')
+end
+```
 
 #### GET a specific user by id (authentication required)
+**Configuration**:
+```ruby
+Bubbles.configure do |config|
+  config.endpoints = [
+    {
+      :method => :get,
+      :location => 'users/{id}',
+      :authenticated => true,
+      :name => :get_user,
+      :return_type => :body_as_object
+    }
+  ]
+
+  config.environment = {
+    :scheme => 'http',
+    :host => '127.0.0.1',
+    :port => '9002'
+  }
+end
+```
+
+**Usage**:
+```ruby
+it 'should return an object containing a user with id = 4' do
+  environment = Bubbles::Resources.new.environment
+  user = environment.get_user(@auth_token, {:id => 4})
+  expect(user).to_not be_nil
+
+  expect(user.id).to eq(4)
+end
+```
 
 #### POST a login (i.e. retrieve an authorization token)
+**Configuration**:
+```ruby
+Bubbles.configure do |config|
+  config.endpoints = [
+    {
+      :method => :post,
+      :location => :login,
+      :authenticated => false,
+      :api_key_required => true,
+      :encode_authorization => [:username, :password],
+      :return_type => :body_as_object
+    }
+  ]
+
+  config.environment = {
+    :scheme => 'http',
+    :host => '127.0.0.1',
+    :port => '9002',
+    :api_key => 'someapikey'
+  }
+end
+```
+
+**Usage**:
+```ruby
+it 'should return a user data structure with a valid authorization token' do
+  environment = Bubbles::Resources.new.environment
+
+  data = { :username => 'myusername', :password => 'mypassword' }
+  login_object = environment.login data
+
+  auth_token = login_object.auth_token
+
+  expect(auth_token).to_not be_nil
+end
+```
 
 #### DELETE a user by id
+**Configuration**:
+```ruby
+Bubbles.configure do |config|
+  config.endpoints = [
+    {
+      :method => :delete,
+      :location => 'users/{id}',
+      :authenticated => true,
+      :name => 'delete_user_by_id',
+      :return_type => :body_as_object
+    }
+  ]
+
+  config.environment = {
+    :scheme => 'http',
+    :host => '127.0.0.1',
+    :port => '9002'
+  }
+```
+
+**Usage**:
+```ruby
+it 'should successfully delete the given user' do
+  environment = Bubbles::Resources.new.environment
+  response = environment.delete_user_by_id @auth_token, {:id => 2}
+  expect(response.success).to eq(true)
+end
+```
 
 #### PATCH a user's information by providing a body containing information to update
+**Configuration**:
+```ruby
+Bubbles.configure do |config|
+  config.endpoints = [
+    {
+      :method => :patch,
+      :location => 'users/{id}',
+      :authenticated => true,
+      :name => 'update_user',
+      :return_type => :body_as_object
+    }
+  ]
+
+  config.environment = {
+    :scheme => 'http',
+    :host => '127.0.0.1',
+    :port => '9002'
+  }
+```
+
+**Usage**:
+```ruby
+it 'should update information for the specified user' do
+  environment = Bubbles::Resources.new.environment
+  response = environment.update_user @auth_token, {:id => 4}, {:user => {:email => 'kleinhammer@somewhere.com' } }
+
+  expect(response.id).to eq(4)
+  expect(response.email).to eq('kleinhammer@somewhere.com')
+end
+```

data/Rakefile

@@ -1,10 +1,5 @@
 require "bundler/gem_tasks"
-require "rake/testtask"
 
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList['test/**/*_test.rb']
-end
+Dir.glob('lib/tasks/*.rake').each { |r| load r}
 
-task :default => :test
+task :default => :build