[![Gem Version](https://badge.fury.io/rb/yext-api.svg)](https://badge.fury.io/rb/yext-api.svg) [![CircleCI](https://circleci.com/gh/CardTapp/yext-api.svg?style=svg)](https://circleci.com/gh/CardTapp/yext-api) [![codecov](https://codecov.io/gh/CardTapp/yext-api/branch/master/graph/badge.svg)](https://codecov.io/gh/CardTapp/yext-api) [![Dependency Status](https://gemnasium.com/badges/github.com/CardTapp/yext-api.svg)](https://gemnasium.com/github.com/CardTapp/yext-api) [![Maintainability](https://api.codeclimate.com/v1/badges/d80882f00aafa1ed5c7b/maintainability)](https://codeclimate.com/github/CardTapp/yext-api/maintainability) # Yext::Api This gem provides a Rails interface with the Yext API. ## Installation Add this line to your application's Gemfile: ```ruby gem 'yext-api' ``` And then execute: $ bundle Or install it yourself as: $ gem install yext-api ## Usage This gem uses the [Spyke gem](https://github.com/balvig/spyke) to simplify the HTML calls and create a familiar ActiveRecord type interface with Yext and the Yext objects. Please refer to that gem for details on making calls, passing paraemters etc. if the documentation here is not sufficient. ### Configuration To use the Yext API, you need to specify certain options like the account ID, the application ID, etc. These options can be set to global defaults or set on a per-call basis. A configuration option is avalable through `Yext::Api.configuration`. All configuration options can be set through here. To confugure multiple items you can use `Yext::Api.configure`: ```ruby Yext::Api.configure do |configuration| configuration.account_id = "your account_id" configuration.api_key = "your application key" configuration.api_version = "20161012" end ``` The global configurations can be initialized with ENV values. The following configurations are available: * `account_id` - `ENV["YEXT_ACCOUNT_ID"]` This is the Account ID that is used in the path to API endpoints that require an account ID. This value will default to `"me"` if not specified. You can specify this on a per-call basis using `account("new account_id")`. This option is only available for objects that require an account ID for all calls. * `api_key` - `ENV["YEXT_API_KEY"]` This is the API_KEY from the Yext Application that you are using. You can specify this on a per-call basis using `application("new application key")`. * `api_version` - `ENV["YEXT_API_VERSION"]` This is the version number of the `v2` API endpoint to be used. This value be defaulted to the most recent version of the API that the gem is aware of or `"2016101"` You can specify this on a per-call basis using `version("new version")`. * `yext_username` - `ENV["YEXT_USERNAME"]` This is the username to be associated with changes in Yext. This option is available on all calls but will only be used for `PUT`, `PATCH`, `CREATE`, and `DELETE` calls. You can specify this on a per-call basis using `yext_username("your username")`. * `yext_user_id` - `ENV["YEXT_USER_ID"]` This is the ID of the user to be associated with changes in Yext. This option is available on all calls but will only be used for `PUT`, `PATCH`, `CREATE`, and `DELETE` calls. You can specify this on a per-call basis using `yext_user_id("your user_id")`. * `validation_level` - `ENV["YEXT_VALIDATION_LEVEL"]` The validation level to be used on the call. This value can only be `strict` or `lenient`. Yext will default this if not specified to "strict" if you do not specify a value. You can specify this on a per-call basis using: * `validate(true)` (for strict) * `validate(false)` (for lenient) * `validate(Yext::Api::Enumerations::Validation::LENIENT)` * `sandbox` - `!Rails.env.production?` Wether or not to use the Sandbox API endpoint or the API endpoint. This option cannot be set on a per-call basis. This option is ignored for all objects under the `LiveApi` namespace. ### General Usage The API namespaces are setup to mimic the structure of the Yext API documentation to make it easier to find or guess at an objects name. Objects are defined based on the routes for those objects. In general to see what an object will look like or what to pass in as arguments to some custom routes that update or create objects, please refer to the Yext API documentation: * http://developer.yext.com/docs/api-reference/ * http://developer.yext.com/docs/administrative-api/ * http://developer.yext.com/docs/live-api/ * http://developer.yext.com/docs/webhooks/ The config/api.yml file contains links to the documentation for every action. In general, each class should also include the same information to point you at/to the related documentation. The following classes are planned based on that structure: * AdministrativeApi::Account * AdministrativeApi::AddRequest * AdministrativeApi::Service * KnowledgeApi::HealthCheck::Health * KnowledgeApi::KnowledgeManager::Location * KnowledgeApi::KnowledgeManager::Folder * KnowledgeApi::KnowledgeManager::Menu * KnowledgeApi::KnowledgeManager::Bio * KnowledgeApi::KnowledgeManager::Product * KnowledgeApi::KnowledgeManager::Event * KnowledgeApi::KnowledgeManager::Category * KnowledgeApi::KnowledgeManager::GoogleField * KnowledgeApi::KnowledgeManager::CustomField * KnowledgeApi::KnowledgeManager::LanguageProfile * KnowledgeApi::KnowledgeManager::Asset * KnowledgeApi::PowerListings::Publisher * KnowledgeApi::PowerListings::Listing * KnowledgeApi::PowerListings::PublisherSuggestion * KnowledgeApi::Analytics::MaxDate * KnowledgeApi::Analytics::Report * KnowledgeApi::Analytics::Activity * KnowledgeApi::Reviews::Review * KnowledgeApi::Reviews::Comment * KnowledgeApi::Reviews::ReviewInvitation * KnowledgeApi::Reviews::ReviewGenerationSetting * KnowledgeApi::Social::Post * KnowledgeApi::Social::Comment * KnowledgeApi::Social::LinkedAccount * KnowledgeApi::AccountSettings::Role * KnowledgeApi::AccountSettings::User * KnowledgeApi::AccountSettings::Account * KnowledgeApi::OptimizationTasks::OptimizationTask * LiveApi::Menu * LiveApi::Bio * LiveApi::Product * LiveApi::Event * LiveApi::LanguageProfile * LiveApi::LanguageProfileSchema * LiveApi::Location * LiveApi::LocationSchema #### Fetching a list of objects Use `all`: ```ruby Yext::Api::AdministrativeApi::Account.all.each do |account| sku_match?(account.sku) end ``` #### Fetching a single object Use `find` ```ruby account = Yext::Api::AdministrativeApi::Account.find("my-id") ``` #### Overriding configuration options ```ruby other_account_services = Yext::Api::AdministrativeApi::Service.account("6664444").application("777821019292928").to_a ``` #### Using custom actions ```ruby available_services = Yext::Api::AdministrativeApi::Service.available.to_a ``` #### API Rate Limits Yext returns rate limit information for each call. This information is different for each category of API call, so it is stored in the base Namespace for each call. NOTE: Accounts are listed in the API documentation in both the `AdministrativeApi` and the `KnowledgeApi` namespaces. The `index` and `get` options are available in both locations, but the rate limites are ONLY recorded in `KnowledgeApi`. ```ruby Yext::Api::AdministrativeApi::Service.all.to_a # Now the following values are set based on the response. Yext::Api::AdministrativeApi.rate_limit_limit Yext::Api::AdministrativeApi.rate_limit_remaining Yext::Api::AdministrativeApi.rate_limit_reset_at ``` ## Development After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also 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`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, 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]/yext-api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. ## License The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). ## Code of Conduct Everyone interacting in the Yext::Api project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/yext-api/blob/master/CODE_OF_CONDUCT.md).