yext-api 0.1.1

data/lib/yext/api/concerns/rate_limits.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Concerns
+      # This module adds attributes to a module for saving and setting the rate limits returned
+      # from the Yext API.
+      module RateLimits
+        attr_reader :rate_limit_remaining,
+                    :rate_limit_limit,
+                    :rate_limit_reset_at,
+                    :last_status,
+                    :last_meta
+
+        def last_status=(last_status)
+          @last_status = last_status
+        end
+
+        def last_meta=(last_meta)
+          @last_meta = last_meta
+        end
+
+        def update_rates(remaining: 1_000, limit: 1_000, reset_at: Time.now)
+          @rate_limit_limit     = limit
+          @rate_limit_remaining = remaining
+          @rate_limit_reset_at  = reset_at
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    # The base engine class for the API.
+    class Engine < ::Rails::Engine
+      isolate_namespace Yext::Api
+
+      # Add a load path for this specific Engine
+      config.autoload_paths << File.expand_path("../../../../lib", __FILE__)
+    end
+  end
+end

data/lib/yext/api/enumerations/validation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Enumerations
+      # An enumeration class to contain the allowable values for the validation option on
+      # API calls.
+      class Validation
+        include Yext::Api::Concerns::EnumAll
+
+        STRICT  = "strict"
+        LENIENT = "lenient"
+      end
+    end
+  end
+end

data/lib/yext/api/knowledge_api.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    # http://developer.yext.com/docs/api-reference
+    #
+    # Yext Knowledge API
+    module KnowledgeApi
+      extend Yext::Api::Concerns::RateLimits
+    end
+  end
+end

data/lib/yext/api/knowledge_api/account_settings/account.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module KnowledgeApi
+      module AccountSettings
+        # :administrative_api:
+        #   :account_settings:
+        #     :account:
+        #       :actions:
+        #         - :action: :index
+        #           :method: :get
+        #           :endpoint: https://api.yext.com/v2/accounts
+        #           :path_regex: v2/accounts
+        #           :default_version: 20161012
+        #           :documentation: http://developer.yext.com/docs/administrative-api/#operation/listAccounts
+        #           :comment: List all accounts that you have access to. Unless you are in Partner Portal mode, this will only be your own account.
+        #           :sandbox_only: false
+        #         - :action: :show
+        #           :method: :get
+        #           :endpoint: https://api.yext.com/v2/accounts/{accountId}
+        #           :path_regex: v2/accounts/\w+
+        #           :default_version: 20161012
+        #           :documentation: http://developer.yext.com/docs/administrative-api/#operation/getAccount
+        #           :comment: Get details for an account.
+        #           :sandbox_only: false
+        class Account < Yext::Api::Utils::ApiBase
+          include Yext::Api::Concerns::AccountRelations
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/knowledge_api/health_check/health.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module KnowledgeApi
+      module HealthCheck
+        # :knowledge_api:
+        #   :health_check:
+        #     :health:
+        #       :actions:
+        #         - :action: :index
+        #           :method: :get
+        #           :endpoint: https://api.yext.com/v2/healthy
+        #           :path_regex: v2/healthy
+        #           :default_version: 20161012
+        #           :documentation: http://developer.yext.com/docs/api-reference/#operation/healthCheck
+        #           :comment: The Health Check endpoint allows you to monitor the status of Yext's systems.
+        #           :sandbox_only: false
+        class Health < Yext::Api::Utils::ApiBase
+          uri("healthy")
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/knowledge_api/knowledge_manager/category.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module KnowledgeApi
+      module KnowledgeManager
+        # :knowledge_api:
+        #   :knowledge_manager:
+        #     :category:
+        #       :actions:
+        #         - :action: :index
+        #           :method: :get
+        #           :endpoint: https://api.yext.com/v2/categories
+        #           :default_version: 20161012
+        #           :documentation: http://developer.yext.com/docs/api-reference/#operation/getBusinessCategories
+        #           :comment: Get available Categories.
+        #           :sandbox_only: false
+        #
+        # Class for fetching categories
+        class Category < Yext::Api::Utils::ApiBase
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/knowledge_api/knowledge_manager/location.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# TODO: Complete and test.  Untested initial framework class.
+module Yext
+  module Api
+    module KnowledgeApi
+      module KnowledgeManager
+        # :knowledge_api:
+        #   :knowledge_manager:
+        #     :Location:
+        #       - :action: :index
+        #         :method: :get
+        #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/locations
+        #         :path_regex: v2/accounts/[^/]+?/locations
+        #         :default_version: 20161012
+        #         :documentation: http://developer.yext.com/docs/api-reference/#operation/getLocations
+        #         :comment: Get multiple Locations (primary profiles only).
+        #         :sandbox_only: false
+        #       - :action: :create
+        #         :method: :post
+        #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/locations
+        #         :path_regex: v2/accounts/[^/]+?/locations
+        #         :default_version: 20161012
+        #         :documentation: http://developer.yext.com/docs/api-reference/#operation/createLocation
+        #         :comment: Create a new Location.
+        #         :sandbox_only: false
+        #       - :action: :search
+        #         :method: :get
+        #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/locationsearch
+        #         :path_regex: v2/accounts/[^/]+?/locationsearch
+        #         :default_version: 20161012
+        #         :documentation: http://developer.yext.com/docs/api-reference/#operation/searchLocations
+        #         :comment: Get multiple Locations (primary profiles only) that match provided filters.
+        #         :sandbox_only: false
+        #       - :action: :show
+        #         :method: :get
+        #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/locations/{locationId}
+        #         :path_regex: v2/accounts/[^/]+?/locations/[^/]+??
+        #         :default_version: 20161012
+        #         :documentation: http://developer.yext.com/docs/api-reference/#operation/getLocation
+        #         :comment: Gets the primary profile for a single Location.
+        #         :sandbox_only: false
+        #       - :action: :update
+        #         :method: :put
+        #         :endpoint: https://api.yext.com/v2/accounts/{accountId}/locations/{locationId}
+        #         :path_regex: v2/accounts/[^/]+?/locations/[^/]+??
+        #         :default_version: 20161012
+        #         :documentation: http://developer.yext.com/docs/api-reference/#operation/updateLocation
+        #         :comment: Updates the primary profile for a Location.
+        #         :sandbox_only: false
+        class Location < Yext::Api::Utils::ApiBase
+          include Yext::Api::Concerns::AccountChild
+
+          # TODO: Custom endpoints
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/live_api.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    # http://developer.yext.com/docs/api-reference
+    #
+    # Yext Knowledge API
+    module LiveApi
+      extend Yext::Api::Concerns::RateLimits
+    end
+  end
+end

data/lib/yext/api/live_api/location.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module LiveApi
+      # :live_api:
+      #   :objects:
+      #     :location:
+      #       :has_many: language_profile
+      #       :has_many: location_schema
+      #       :actions:
+      #         - :action: :index
+      #           :method: :get
+      #           :endpoint: https://liveapi.yext.com/v2/accounts/{accountId}/locations
+      #           :path_regex: https://liveapi.yext.com/v2/accounts/[^/]+?/locations
+      #           :default_version: 20161012
+      #           :documentation: http://developer.yext.com/docs/live-api/#operation/locationsList
+      #           :comment: >
+      #             Get multiple Locations (primary profile only). Filters are evaluated against all language
+      #             profiles as well as the primary profile.
+      #           :sandbox_only: false
+      #         - :action: :show
+      #           :method: :get
+      #           :endpoint: https://liveapi.yext.com/v2/accounts/{accountId}/locations/{locationId}
+      #           :path_regex: https://liveapi.yext.com/v2/accounts/[^/]+?/locations/[^/]+??
+      #           :default_version: 20161012
+      #           :documentation: http://developer.yext.com/docs/live-api/#operation/getLocation
+      #           :comment: Gets the primary profile for a single Location.
+      #           :sandbox_only: false
+      class Location < Yext::Api::Utils::ApiBase
+        include Yext::Api::Concerns::AccountChild
+
+        live_api
+      end
+    end
+  end
+end

data/lib/yext/api/utils/api_base.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Utils
+      # The base class for the Yext API components.
+      class ApiBase < Spyke::Base
+        include Yext::Api::Concerns::FaradayConnection
+        include Yext::Api::Concerns::DefaultScopes
+      end
+    end
+  end
+end

data/lib/yext/api/utils/api_rate_limits.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Utils
+      # Faraday Middleware for extracting API limits from call responses.
+      class ApiRateLimits < Faraday::Response::Middleware
+        include Yext::Api::Concerns::ApiFinder
+
+        def call(env)
+          @app.call(env).on_complete do |environment|
+            save_rates(environment, find_api(env[:url], env[:method].to_s))
+
+            env.response
+          end
+        end
+
+        private
+
+        def save_rates(environment, api_module)
+          return if api_module.blank?
+
+          api_module.last_status = environment[:status]
+
+          response_headers = environment[:response_headers]
+
+          return unless response_headers.key?("rate-limit-remaining")
+
+          api_module.update_rates(remaining: response_headers["rate-limit-remaining"].to_i,
+                                  limit:     response_headers["rate-limit-limit"].to_i,
+                                  reset_at:  Time.at(response_headers["rate-limit-reset"].to_i))
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/utils/configuration.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Utils
+      # A configuration class for global configurations for interfacing with the Yext API.
+      #
+      # The class is a Singleton class to simplify accessing the configuration.
+      #
+      # Documentation for how the various configurations are used within Yext can be found here:
+      #   http://developer.yext.com/docs/administrative-api/#section/Policies-and-Conventions
+      #
+      # Initialization:
+      #   Some values within the
+      #
+      # The configurations:
+      #
+      # account_id
+      #   *required*
+      #   default: "me"
+      #   The ID of the account which you are interfacing with.
+      #
+      #   If the default value of "me" is used, the account_id will default to the account which owns the
+      #   api_key.
+      #
+      # api_key
+      #   *required*
+      #   The API key for the Yext Application which is being used to submit the request through.
+      #
+      # api_version
+      #   The version of the Yext API that the request would like to use for any given API call.
+      #
+      #   If left as nil, the gem will try to use the most up-to-date known version of all APIs whenever
+      #   possible, and future updates will adjust the defaults for each call to the most recent known
+      #   version of the API.
+      #
+      #   To keep your application stable, you should set this value to a static known value (such as
+      #   the date the project using the Yext API first started development).
+      #
+      #   The Yext API will accept a default of "20161012" to use the initially released v2 API.
+      #
+      # validation_level
+      #   The validation level to use for a request.  Yext defaults this to "strict".  You can set this to
+      #   "lenient" to allow more lenient error and warning handling on your requests.
+      #
+      #   Validation should be a value from Yext::Api::Enumerations::Validation
+      #
+      # yext_username
+      #   The username of a Yext User that the call is being made on the behalf of.  This will affect the
+      #   logging of who made a change.
+      #
+      # yext_user_id
+      #   The id of a Yext User that the call is being made on the behalf of.  This will affect the
+      #   logging of who made a change.
+      #
+      # sandbox
+      #   Boolean that indicates if the gem should use the production or sandbox URL.
+      class Configuration
+        include Singleton
+
+        attr_accessor :account_id,
+                      :api_key,
+                      :api_version,
+                      :yext_username,
+                      :yext_user_id,
+                      :sandbox
+        attr_reader :validation_level
+
+        def initialize
+          read_from_environment_variables
+        end
+
+        def validation_level=(value)
+          if (value.present? || value == false) &&
+              !Yext::Api::Enumerations::Validation.all.include?(value)
+            raise ArgumentError, "validation must be one of: #{Yext::Api::Enumerations::Validation.all.join(',')}"
+          end
+
+          @validation_level = value
+        end
+
+        private
+
+        def read_from_environment_variables
+          @sandbox = !Rails.env.production?
+
+          @account_id       = ENV["YEXT_ACCOUNT_ID"]
+          @api_key          = ENV["YEXT_API_KEY"]
+          @api_version      = ENV["YEXT_API_VERSION"]
+          @validation_level = ENV["YEXT_VALIDATION_LEVEL"]
+          @yext_username    = ENV["YEXT_USERNAME"]
+          @yext_user_id     = ENV["YEXT_USER_ID"]
+        end
+      end
+    end
+  end
+end

data/lib/yext/api/utils/default_parameters.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Yext
+  module Api
+    module Utils
+      # Faraday Middleware for adding Configuration default values to API calls as needed.
+      #
+      # Most options can be set via scopes and the soped values will be kept if they are used.
+      #
+      # The following configuration options are defaulted:
+      #   validation_level: Added to query parameters if not already there and is not nil
+      #   api_key:          Added to query parameters if not already there
+      #   api_version:      Added to qeury parameters if not already there
+      #   account_id:       Inserted into the path if the path includes the Account default URI and no
+      #                     account_id was specified.
+      class DefaultParameters < Faraday::Response::Middleware
+        attr_reader :configuration
+
+        def call(request_env)
+          @configuration = Yext::Api.configuration
+          url            = request_env[:url]
+          params         = Rack::Utils.parse_nested_query(url.query).with_indifferent_access
+
+          add_username_headers(request_env, configuration, params)
+          add_default_query_params(configuration, params)
+          save_query_params(url, params)
+
+          @app.call(request_env)
+        end
+
+        private
+
+        def add_default_query_params(configuration, params)
+          params.reverse_merge!(api_key: configuration.api_key,
+                                v:       configuration.api_version || "20161012")
+
+          params[:validation] ||= configuration.validation_level if configuration.validation_level.present?
+        end
+
+        def save_query_params(url, params)
+          url.query = params.to_query
+        end
+
+        def add_username_headers(request_env, configuration, params)
+          username = params.delete(:yext_username) || configuration.yext_username
+          user_id  = params.delete(:yext_user_id) || configuration.yext_user_id
+
+          return unless %w[put post patch delete].include?(request_env[:method].to_s)
+
+          request_headers                  = request_env[:request_headers]
+          request_headers["Yext-Username"] = username if username.present?
+          request_headers["Yext-User-Id"]  = user_id if user_id.present?
+        end
+      end
+    end
+  end
+end