lotrb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 398451af707693c91bb01a514d7fc2904503eb7346d6c27469e166bfaf8290eb
-  data.tar.gz: 7fa3490c0ee78f67c73d8b87c0f99ea7f17d01b7ceed4032e21408f233dbbe56
+  metadata.gz: 52385f21be1c97b5fe3f27c83990285962232bee6d63037e123b9beff3e406fb
+  data.tar.gz: 1219ce4918de4e07a2b8117ab02db08e760492a820008d8d8b78c13ae9d842cb
 SHA512:
-  metadata.gz: 0125e24d31abbca650a9081697fc9c433e9f8906d85f452ea51aa59b3d103a4aac93eaba6f2c60bd478dd81f24bd68abae40a8f4cbd88b95712040f95c819601
-  data.tar.gz: c1ae860fd3c1f2e81f78f0c70991826135a2ec47d238c36eee82716a937cf1d36a9747182d1ebfe73f3218e37635f428d3ac390b99ee3ee38f9744a172e0a33e
+  metadata.gz: 164f3c60d7429801220da1e19a68c8fd6a08cc3de1eeaf6f2c37425dd39be619071bf3ab4bc0be8dcd45b5d7cb203c2abda89f9496e8d5f775e4d67bd2a59f07
+  data.tar.gz: 02ca9a45196f3a5456a0ab23a864698d13d9c434035ec360a32b2d5bd51d27c11f26114d0255ea293257e70ff86519d21c5df4d19b8675dd9d3a39d688e1317e

data/DESIGN.md

@@ -0,0 +1,36 @@
+# SDK Design Notes
+
+My goals in writing `lotrb` were the following:
+1) get something _working_ -- in truth, I've never written a Ruby gem OR any sort of SDK before
+2) build something with a relatively simple, straightforward interface
+3) write as little code as possible, within reason
+
+The SDK mirrors the API fairly closely. I took a good amount of inspiration from [Stripe's ruby library](https://github.com/stripe/stripe-ruby), because it's one of the most pleasant I've worked with.
+
+The most satisfying part of this SDK so far is the way it maps fields in the objects from the JSON response into Ruby objects without going crazy with any explicit mapping or config, etc. I do this by a bit of metaprogramming to convert the JSON field names into `attr_accessor`s on the relevant class and then set each field's value as it's "hydrated," if you will. For example, the `Book` class doesn't have a `name` field defined in code -- it's dynamically defined and assigned when we hydrate each `Book` instance from an API response.
+
+We can list any resource type (Book, Movie, Chapter, Character, and Quote) by calling the class method `list` on the corresponding class. This will return a `ListObject` containing an array of the corresponding resource objects along with the pagination fields:
+
+```ruby
+characters = Lotrb::Character.list # This will give you a ListObject
+characters.results # This will give you the array of Character objects
+characters.pages # This will give you the number of pages in the result of you list request
+
+# Since `characters.results` is a plain Ruby array, we can access it like any old array:
+characters.results.first.name
+```
+
+Likewise, we can fetch a single resource by ID by calling the class method `retrieve` on the corresponding class. This will return an instance of the class itself.
+
+```ruby
+quote = Lotrb::Quote.retrieve("5cd96e05de30eff6ebccebca") # This returns an actual Quote object
+quote.dialog # This returns the dialog field of the quote
+```
+
+Finally (and this is a piece I'm not very happy with yet), classes for which the API allows fetching nested resources each have a `list_blahs` method, where `blah` is the nested resource. This `list_blahs` method quacks just like a `list` method on one of the resource classes, returning a `ListObject`. For example...
+
+```ruby
+book = Lotrb::Book.list.results.first # Returns a ListObject
+book.list_chapters.results # Returns an array of Chapter objects
+```
+

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lotrb (0.1.0)
+    lotrb (0.2.0)
       faraday (~> 1.7)
       faraday_middleware (~> 1.1)
 

data/README.md

@@ -30,10 +30,30 @@ require "lotrb"
 Lotrb.access_token = "your_access_token_here"
 
 # List all the movies
-Lotrb::Movie.list()
+# This returns a `ListObject` containing an array of the corresponding resource objects along with the pagination fields
+movies_response = Lotrb::Movie.list
+movies_response.results
+movies_response.pages 
 
 # Fetch a specific movie
-Lotrb::Movie.retrieve("some_movie_id")
+Lotrb::Movie.retrieve("5cd95395de30eff6ebccde5d")
+
+# Fetch the chapters from a book
+book = Lotrb::Book.list.results.last
+book.list_chapters
+
+# Pagination, sorting, and filtering all work by passing a hash of 
+# params to any `list` or `list_blahs` call.
+# These params map precisely to those described in [the API docs](https://the-one-api.dev/documentation)
+#
+# Paginate!
+Lotrb::Quote.list({ limit: 5, page: 75 })
+
+# Sort!
+Lotrb::Book.list({ sort: "name:asc" })
+
+# Filter!
+Lotrb::Character.list({ race: "Hobbit,Human" })
 ```
 
 ## Development
@@ -44,7 +64,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/lotrb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/lotrb/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/danielmklein/lotrb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/danielmklein/lotrb/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -52,4 +72,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Lotrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/lotrb/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the lotrb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/danielmklein/lotrb/blob/main/CODE_OF_CONDUCT.md).

data/lib/lotrb/TODO.md

@@ -1,6 +1,3 @@
 # TODOS
-- pagination stuff
-- other actions than list
-- other resources than movie
 - write tests
-- 
+- more elegant nested object support

data/lib/lotrb/client.rb

@@ -1,8 +1,6 @@
 require "faraday"
 require "faraday_middleware"
 
-# client.connection.get("movie", {}, { Authorization: "Bearer #{Lotrb.access_token}" }).body["docs"]
-
 module Lotrb
   class Client
     BASE_URL = "https://the-one-api.dev/v2/"
@@ -26,12 +24,8 @@ module Lotrb
       end
     end
 
-    def inspect
-      "#<Lotrb::Client>"
-    end
-
-    def get(path, opts = {})
-      connection.get(path, opts, auth_header)
+    def get(path, params = {})
+      connection.get(path, params , auth_header)
     end
 
     private

data/lib/lotrb/list_object.rb

@@ -1,6 +1,10 @@
 module Lotrb
+  # A data structure to hold list results from an API request
+  # `results` holds the actual POROs representing the data,
+  # while `total`, `limit`, `offset`, `page`, and `pages`
+  # hold the corresponding pagination values from the API.
   class ListObject
-    attr_reader :objects, :total, :limit, :offset, :page, :pages
+    attr_reader :results, :total, :limit, :offset, :page, :pages
   
     def initialize(result, klass)
       @total = result["total"]
@@ -8,7 +12,7 @@ module Lotrb
       @offset = result["offset"]
       @page = result["page"]
       @pages = result["pages"]
-      @objects = result["docs"].map do |hash|
+      @results = result["docs"].map do |hash|
         klass.from_result_hash(hash)
       end
     end

data/lib/lotrb/resources/base_resource.rb

@@ -1,26 +1,45 @@
 module Lotrb
-  class BaseResource
-    def self.list
-      ListObject.new(Client.instance.get(self::RESOURCE_NAME).body, self)
+  class BaseResource  
+    # The fundamental method for fetching a list of resources from the API.
+    def self.list(params = {})
+      child_class = self
+      path = self::RESOURCE_NAME
+      internal_get(path: path, params: params, result_class: child_class)
     end
 
+    # The fundamental method for fetching a specific resource from the API, by ID.
     def self.retrieve(id)
+      child_class = self
       path = "#{self::RESOURCE_NAME}/#{id}"
-      ListObject.new(Client.instance.get(path).body, self).objects.first
+      internal_get(path: path, result_class: child_class).results.first
     end
 
     # Take a hash that represents an object (from JSON),
     # convert the field names to snake case (to be ruby-ish)
     # and metaprogram those fields onto object, and return it.
+    #
+    # This is used throughout for taking a single entry from an API result
+    # and mapping it into a Ruby object with the fields we might expect.
+    # The metaprogramming here allows us to avoid having to explicitly
+    # specify the fields we are expecting in the response -- the resulting
+    # Ruby object will have all the fields that the response object did.
     def self.from_result_hash(result_hash)
-      object = new
+      poro = new
       result_hash.each do |(field_name, field_value)|
         snake_case_field_name = Util.to_snake_case(field_name)
-        object.class.attr_accessor(snake_case_field_name)
-        object.send("#{snake_case_field_name}=", field_value)
+        poro.class.attr_accessor(snake_case_field_name)
+        poro.send("#{snake_case_field_name}=", field_value)
       end
 
-      object
+      poro
+    end
+
+    # All `list`, `retrieve`, and `list_blahs` calls go through this method.
+    # Use the API client to get the response (validating the params along the way),
+    # then map the results to the right class.
+    def self.internal_get(path:, params: {}, result_class:)
+      response_body = Client.instance.get(path, params).body
+      ListObject.new(response_body, result_class)
     end
   end
-end
+end

data/lib/lotrb/resources/book.rb

@@ -1,5 +1,11 @@
 module Lotrb
   class Book < BaseResource
     RESOURCE_NAME = "book"
+
+    def list_chapters(params = {})
+      child_class = Chapter
+      path = "#{RESOURCE_NAME}/#{_id}/#{child_class::RESOURCE_NAME}"
+      self.class.internal_get(path: path, params: params, result_class: child_class)
+    end
   end
 end

data/lib/lotrb/resources/character.rb

@@ -1,5 +1,11 @@
 module Lotrb
   class Character < BaseResource
     RESOURCE_NAME = "character"
+
+    def list_quotes(params = {})
+      child_class = Quote
+      path = "#{RESOURCE_NAME}/#{_id}/#{child_class::RESOURCE_NAME}"
+      self.class.internal_get(path: path, params: params, result_class: child_class)
+    end
   end
 end

data/lib/lotrb/resources/movie.rb

@@ -1,5 +1,11 @@
 module Lotrb
   class Movie < BaseResource
     RESOURCE_NAME = "movie"
+
+    def list_quotes(params = {})
+      child_class = Quote
+      path = "#{RESOURCE_NAME}/#{_id}/#{child_class::RESOURCE_NAME}"
+      self.class.internal_get(path: path, params: params, result_class: child_class)
+    end
   end
 end

data/lib/lotrb/version.rb

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

data/lib/lotrb.rb

@@ -4,7 +4,6 @@ require_relative "lotrb/version"
 
 require "lotrb/list_object"
 require "lotrb/resources"
-
 require "lotrb/util"
 
 module Lotrb
@@ -13,6 +12,5 @@ module Lotrb
 
   class << self
     attr_accessor :access_token
-
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lotrb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Daniel Klein