the_one_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eab63a106b4736953d1eaf773cfef554b7fe9a83984a7cd41596451e31c01834
+  data.tar.gz: 6be4a461d074122e439f9a6bb08cdb3018917d81c0a717d43239610e9b58d7d8
+SHA512:
+  metadata.gz: fade730fc33c878c40b9d1fad97f63385d64217ddfd7fb3a0902288476638b1cbae460e253d8fb8977d7761bbae069edf8799ee46285281561f28987eb23dbec
+  data.tar.gz: 7ce96e59be310e63a6c70f04e44ec11f26ef04c61aba60ef3d8e61728b127359387e0d404fd942dcf501a0c1bf65567d5ae2d30522d393d3d93b27d10f0dd126

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,15 @@
+AllCops:
+  NewCops: disable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.2.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Joshua Samberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,127 @@
+# TheOneApi
+
+This is a Ruby gem that provides an SDK for interacting with [The One API](https://the-one-api.dev/)
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+You don't need this source code unless you want to modify the gem. If you just want to use the package, just run:
+
+    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+
+If you want to build the gem from source:
+
+    $ gem build UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+### Installing with Bundler
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+### Requirements
+
++ Ruby 3.0+
+
+## Usage
+
+Interact with [The One API](https://the-one-api.dev/) through an instance of `TheOneApi::Client`. To create one you must specify your API Key, which is required by most endpoints:
+
+```ruby
+require 'the_one_api'
+
+# Replace "your-api-key" with your actual API key
+client = TheOneApi::Client.new("your-API-key")
+```
+
+### Querying Data
+
+Query root level API resources (e.g. `/movie`) through corresponding named methods on the client. API entities are returned as Ruby objects.
+
+```ruby
+require 'the_one_api'
+
+client = TheOneApi::Client.new("your-API-key")
+
+# list movies with the movie resource (the /movie endpoint)
+movies = client.movie.list
+movies.count
+# => 8
+
+# find one movie by its id with the movie resource (the /movie/{id} endpoint)
+movie = client.movie.find("5cd95395de30eff6ebccde57")
+#=> #<TheOneApi::Movie _id: "5cd95395de30eff6ebccde57", name: "The Hobbit Se..
+
+# properties of API entites available as snake-ized named members on the returned objects
+movie.runtime_in_minutes
+#=> 462
+
+```
+
+### Errors
+
+The client will raise `TheOneApi::HttpResponseError` when a request returns a bad status code:
+
+```ruby
+require 'the_one_api'
+
+client = TheOneApi::Client.new("your-API-key")
+
+begin
+    client.movie.find("does_not_exist") # raises an error
+rescue TheOneApi::HttpResponseError => e
+    puts "Failed to find movie with id 'does_not_exist', error code: #{e.status}, error: #{e.message}"
+end
+```
+
+**Note:** [The One API](https://the-one-api.dev/) DOES NOT return standard HTTP errors, for example the above example returns a `500 Internal Server Error`, not a `404 Not Found`.
+
+## Supported API Features
+
+### Currently Supported Root Level Endpoints/Operations
+
++ `/movie` - list all movies, find a movie by id
+
+### Currently Unsupported Features
+
+The SDK currently does not explicitly support
++ root level endpoints not listed above
++ nested endpoints - e.g. `/movie/{id}/quote`
++ Pagination, Sorting and Filtering as described [here](https://the-one-api.dev/documentation#5)
+
+However, you can supply custom query parameters as a hash to any of the named resource methods on `TheOneApi::Client`, for example:
+
+```ruby
+require 'the_one_api'
+
+client = TheOneApi::Client.new("your-API-key")
+
+# this request will have special_parameter=value added to its query string
+client.movie.list(special_parameter: "value")
+```
+
+
+## Development
+
+After checking out the repo:
++ run `bin/setup` to install dependencies
++ run `bundle exec rake test` to run the tests
++ 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`
+
+To release a new version
++ update the version number in `version.rb`
++ run `bundle exec rake release`
+    * this will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+<!-- ## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/the_one_api. -->
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/the_one_api/client.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "the_one_api/resource_wrapper"
+require "the_one_api/resources/movie"
+
+module TheOneApi
+  # A client for The One Api
+  class Client
+    BASE_URL = "https://the-one-api.dev/v2/"
+
+    Flexirest::Base.base_url = BASE_URL
+    Flexirest::Base.faraday_config do |faraday|
+      faraday.adapter(:net_http)
+    end
+
+    def initialize(api_key)
+      @api_key = api_key
+    end
+
+    def movie
+      @movie ||= ResourceWrapper.new(Movie, @api_key)
+    end
+  end
+end

data/lib/the_one_api/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TheOneApi
+  class Error < StandardError; end
+end

data/lib/the_one_api/http_response_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TheOneApi
+  # Our own error class to throw for HTTP response errors
+  #
+  # Good encapsulation to not expose our consumers to the
+  # error types of the underlying libraries unintentionally
+  class HttpResponseError < TheOneApi::Error
+    attr_reader :status
+
+    def initialize(status, msg = nil)
+      @status = status
+      super(msg)
+    end
+  end
+end

data/lib/the_one_api/resource_wrapper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TheOneApi
+  # A client for The One Api
+  class ResourceWrapper
+    def initialize(wrapped_resource, api_key)
+      @wrapped_resource = wrapped_resource
+      @api_key = api_key
+    end
+
+    def method_missing(method, *args, &block)
+      super unless @wrapped_resource._calls.key?(method)
+
+      # merge the api key in with the supplied
+      # arguments so that the request can be authenticated
+      args_with_api_key = if args[0].is_a?(Hash)
+                            (args[0]).merge({ api_key: @api_key })
+                          elsif args[0]
+                            { id: args[0] }.merge({ api_key: @api_key })
+                          else
+                            { api_key: @api_key }
+                          end
+
+      @wrapped_resource.send(method, args_with_api_key, &block)
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      @wrapped_resource._calls.key?(method) || super
+    end
+  end
+end

data/lib/the_one_api/resources/base_resource.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "flexirest"
+
+module TheOneApi
+  # Helper class to implement and wire in the response
+  # transformations needed by BaseResource (see below)
+  class BaseResourceProxy < Flexirest::ProxyBase
+    # if this is a GET request to a single, non-nested resource by id
+    get(+"\\/[^\\/]+\\/[^\\/]+\\z") do
+      response = passthrough
+      translate(response) do |body|
+        # give back the entity instead of an array of one entity
+        body["docs"] && body["docs"][0] ? body["docs"][0] : body
+      end
+    end
+    # if this is a GET request to a root-level resource
+    get(+"\\/[^\\/]+\\z") do
+      response = passthrough
+      translate(response) do |body|
+        # give back the array of returned entities instead of the envelope
+        # structure that surrounds it
+        body["docs"] || body
+      end
+    end
+  end
+
+  # Common functionality for all API resources, including:
+  #   + Adding authentication header
+  #   + Unwrapping the `docs` array
+  #       when listing all entities from a resource
+  #   + Unwrapping the one item returned in the `docs` array
+  #       when requesting a single entity by id
+  class BaseResource < Flexirest::Base
+    proxy BaseResourceProxy
+
+    before_request :add_authentication_header
+    after_request :handle_http_error
+
+    private
+
+    def add_authentication_header(_name, request)
+      return unless request.get_params[:api_key]
+
+      request.headers["Authorization"] = "Bearer #{request.get_params[:api_key]}"
+      request.get_params.delete(:api_key)
+    end
+
+    def handle_http_error(_name, response)
+      return unless response.status && response.status != 200
+
+      raise HttpResponseError.new(response.status,
+                                  response.body["message"])
+    end
+  end
+end

data/lib/the_one_api/resources/movie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "the_one_api/resources/base_resource"
+
+module TheOneApi
+  # Resource definition for Movies
+  class Movie < BaseResource
+    before_request :add_authentication_header
+
+    get :list, "/movie", rubify_names: true
+    get :find, "/movie/:id", rubify_names: true
+  end
+end

data/lib/the_one_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TheOneApi
+  VERSION = "0.1.0"
+end

data/lib/the_one_api.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "the_one_api/version"
+
+# Module containing everything our Gem exports
+module TheOneApi
+  autoload :Client, "the_one_api/client"
+
+  autoload :HttpResponseError, "the_one_api/http_response_error"
+  autoload :Error, "the_one_api/error"
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: the_one_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joshua Samberg
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-06-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: flexirest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.11.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.11.1
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.8.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.52'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.52'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.1.0
+description: An Ruby gem providing an SDK for interacting with The One API
+email:
+- iceberg901@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".tool-versions"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/the_one_api.rb
+- lib/the_one_api/client.rb
+- lib/the_one_api/error.rb
+- lib/the_one_api/http_response_error.rb
+- lib/the_one_api/resource_wrapper.rb
+- lib/the_one_api/resources/base_resource.rb
+- lib/the_one_api/resources/movie.rb
+- lib/the_one_api/version.rb
+homepage: https://github.com/iceberg901/joshua-samberg-sdk
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: An Ruby gem providing an SDK for interacting with The One API
+test_files: []