Document all the things

lib/nasa.rb

@@ -8,6 +8,7 @@
 require 'nasa/configuration'
 require 'nasa/api/rest'
 require 'nasa/api/responses'
+require 'nasa/api/services/neo_ws'
 
 # Main entry to the gem
 module NASA

lib/nasa/api/responses.rb

@@ -1,54 +1,84 @@
 # frozen_string_literal: true
 
 module NASA
-  # Base response class
-  class Response
-    attr_accessor :code, :headers, :body, :message, :raw_response
+  module Response
+    # Base Response
+    class BaseResponse
+      # @!attribute [r] code
+      #   @return [Integer] HTTP Status code
+      # @!attribute [r] headers
+      #   @return [Hash] Parsed HTTP Headers
+      # @!attribute [r] body
+      #   @return [Hash] HTTP Body JSON
+      # @!attribute [r] message
+      #   @return [String] Error message, if any
+      # @!attribute [r] raw_response
+      #   @return [RestClient::Response] Unparsed response
+      # @!attribute [r] remaining_requests
+      #   @return [Integer] Remaining hourly
+      #     requests available
+      attr_reader :code, :headers, :body, :message, :raw_response, :remaining_requests
 
-    def initialize(response)
-      @raw_response = response
-      parse_response(response)
-    end
-  end
+      def initialize(response)
+        @raw_response = response
+        parse_response(response)
+      end
 
-  # Handles and parses non error responses from the API
-  class RestResponse < Response
-    def initialize(response)
-      super(response)
-      parse_response(response)
-    end
+      # JSON {#body} key lookup shorthand
+      # @param [String] key
+      # @return [String] key value.
+      def [](key)
+        @body[key]
+      end
 
-    def parse_response(response)
-      @code = response.code
-      begin
-        @body = JSON.parse(response.body, symbolize_names: true)
-      rescue JSON::ParserError
-        @body = {}
+      # @param [RestClient::Response]
+      # @return nothing, used by #super in decendants
+      def parse_response(response)
+        raise NotImplementedError
       end
-      @headers = response.headers
     end
 
-    def [](key)
-      @body[key]
-    end
-  end
+    # Handles and parses non error responses from the API
+    class RestResponse < BaseResponse
+      def initialize(response)
+        super(response)
+      end
 
-  # Handles and parses error responses from the API
-  class ExceptionResponse < Response
-    def initialize(response)
-      super(response)
-      parse_response(response)
+      # Parses response from successful API calls
+      #
+      # @param [RestClient::Response] response
+      def parse_response(response)
+        @code = response.code
+        begin
+          @body = JSON.parse(response.body, symbolize_names: true)
+        rescue JSON::ParserError
+          @body = {}
+        end
+        @headers = response.headers
+        @remaining_requests = @headers[:'X-RateLimit-Remaining']
+      end
     end
 
-    def parse_response(response)
-      @code = response.http_code
-      begin
-        @body = JSON.parse(response.http_body, symbolize_names: true)
-      rescue JSON::ParserError
-        @body = {}
+    # Handles and parses error responses from the API
+    class ExceptionResponse < BaseResponse
+      def initialize(response)
+        super(response)
+      end
+
+      # Parses response from failed API calls
+      #
+      # @param [RestClient::ExceptionWithResponse] response
+      # @return [Hash] Parsed JSON body from response
+      def parse_response(response)
+        @code = response.http_code
+        begin
+          @body = JSON.parse(response.http_body, symbolize_names: true)
+        rescue JSON::ParserError
+          @body = {}
+        end
+        @message = @body[:message]
+        @headers = response.http_headers
       end
-      @message = @body[:message]
-      @headers = response.http_headers
     end
   end
 end

lib/nasa/api/services/neo_ws.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module NASA
+  module Services
+    # NeoWs (Near Earth Object Web Service)
+    # With NeoWs a user can: search for Asteroids based on their closest approach date to Earth,
+    # lookup a specific Asteroid with its NASA JPL small body id,
+    # as well as browse the overall data-set.
+    module NeoWs
+      # Base API Endpoint for this service
+      ENDPOINT='https://api.nasa.gov/neo/rest/v1/'
+
+      # Retrieve a list of Asteroids based on their closest approach date to Earth.
+
+      # @param [String] start_date formatted as YYYY-MM-DD
+      # @param [String] end_date formatted as YYYY-MM-DD
+      #   defaults to 7 days after start_date
+      # @return [NASA::RestResponse]
+      def feed(start_date, end_date)
+        params = { start_date: start_date, end_date: end_date }
+
+        get("#{ENDPOINT}/feed", params)
+      end
+
+      # Lookup a specific Asteroid based on its NASA JPL small body (SPK-ID) ID
+      #
+      # @param [Integer] asteroid_id Asteroid SPK-ID
+      # @return [NASA::RestResponse]
+      def lookup(asteroid_id)
+        get("#{ENDPOINT}/neo/#{asteroid_id}")
+      end
+
+      # Browse the overall Asteroid data-set
+      # @return [NASA::RestResponse]
+      def browse
+        get("#{ENDPOINT}/neo/browse")
+      end
+    end
+  end
+end

lib/nasa/configuration.rb

@@ -3,8 +3,20 @@
 module NASA
   # Base configuration for the gem
   module Configuration
-    attr_writer :api_key, :debug
+    # @return [String]
+    attr_reader :api_key
+    # @return [Boolean]
+    #  Can be set from {NASA} namespace
+    attr_accessor :debug
 
+    # Configures the gem
+    #
+    # @yield [config]
+    # @yieldparam api_key [String] Sets the NASA API Key
+    #   Can be pulled from ENV `nasa_api_key` or set in
+    #   the configure block
+    # @see https://api.nasa.gov/index.html#apply-for-an-api-key
+    # @yieldparam debug [Boolean] Enable/Disable Rest logging
     def configure
       yield self
     end