gather_content-api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bc4fa4c68863fe799d804ff07fe209eff1e8893b
+  data.tar.gz: fe246d59f62d044e5fb78fc75204490dd8596dcc
+SHA512:
+  metadata.gz: 1163d48c41a4648d40550e237b4d5f8a58e9b3e63ccf8a526880e1bbf8c1c1cd55588937f28975b947eff64751bd25cfab03e6f13456ac84dd5702e0bb8b0b17
+  data.tar.gz: affabeb1a6be1740294f12aad415688305dbc08a0f46949a8d60be34ac719bd58647964817d3aa9cbc0c5ff2778bb9a472d452b354af00e4fe0ff608e4680b07

data/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+Gemfile.lock
+coverage/
+Figsfile
+# Ignore application configuration
+application.yml
+.ruby-version

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.4.2
+sudo: false

data/Gemfile

@@ -0,0 +1,13 @@
+source 'http://rubygems.org'
+gemspec
+
+group :development do
+  gem 'vcr', '~> 3'
+  gem 'webmock', '~> 3'
+  gem 'rspec', '~> 3'
+  gem 'coveralls', require: false
+
+  gem 'pry'
+  gem 'figs', require: false
+  gem 'climate_control', require: false
+end

data/README.md

@@ -0,0 +1,395 @@
+# GatherContent Ruby Client
+
+[![Build Status](https://travis-ci.org/NYULibraries/gather_content-api.svg?branch=master)](https://travis-ci.org/NYULibraries/gather_content-api)
+[![Dependency Status](https://gemnasium.com/badges/github.com/NYULibraries/gather_content-api.svg)](https://gemnasium.com/github.com/NYULibraries/gather_content-api)
+[![Maintainability](https://api.codeclimate.com/v1/badges/ace52f297d3f4160799d/maintainability)](https://codeclimate.com/github/NYULibraries/gather_content-api/maintainability)
+[![Coverage Status](https://coveralls.io/repos/github/NYULibraries/gather_content-api/badge.svg?branch=master)](https://coveralls.io/github/NYULibraries/gather_content-api?branch=master)
+
+This gem is a light wrapper around the [GatherContent API](https://docs.gathercontent.com/reference).
+
+All the endpoints are represented by Objects. Collective Objects (ie Projects, Items etc) are Enumerable, allowing you to loop over them. Singular Objects act like Hashes, giving access to the data via keys.
+
+You can access the underlying data of a Singular Object by using the ```#fetch``` method. The ```#fetch``` method will cache the result - if you want to clear the result, call ```#reset```
+
+# Usage
+
+## Authentication
+
+There are two was to setup [authentication](https://docs.gathercontent.com/reference#authentication):
+
+1. using the _Config_ object
+2. via Environmental variables
+
+### The Config Object
+
+```ruby
+GatherContent::Api::Config.run do |config|
+  config.username = "Your GatherContent username"
+  config.api_key = "Your GatherContent API key"
+end
+```
+
+### Environmental Variables
+
+```bash
+export GATHER_CONTENT_API_USERNAME="Your GatherContent username"
+export GATHER_CONTENT_API_KEY="Your GatherContent API key"
+ruby script_that_uses_the_gem.rb
+```
+
+## Me
+
+You have access to all fields of information about the logged in User such as their avatar url, name, and other fields. [Sample Response](https://docs.gathercontent.com/reference#get-me)
+
+
+```ruby
+require 'gather_content'
+
+me = GatherContent::Api::Me.new
+me["email"]
+=> "andrew@gathercontent.com"
+
+me["first_name"]
+=> "Andrew"
+```
+
+## Accounts
+
+Retrieves a list of all Accounts associated with the authenticated user. [Sample Response](https://docs.gathercontent.com/reference#get-accounts)
+
+```ruby
+require 'gather_content'
+
+accounts = GatherContent::Api::Accounts.new
+accounts.each do |account|
+  puts account["id"]
+  puts account["name"]
+end
+```
+
+## Account
+
+Retrieve a specific account. [Sample Response](https://docs.gathercontent.com/reference#get-accountsaccount_id)
+
+```ruby
+require 'gather_content'
+
+account_id = 123456
+accounts = GatherContent::Api::Account.new(account_id)
+
+account["id"]
+=> 123456
+
+account["name"]
+=> "Example"
+```
+
+## Projects
+
+Retrieves a list of all Projects associated with the given Account. [Sample Response](https://docs.gathercontent.com/reference#get-projects)
+
+```ruby
+require 'gather_content'
+
+account_id = 123456
+projects = GatherContent::Api::Projects.new(account_id)
+
+projects.each do |project|
+  puts project["id"]
+  puts project["name"]
+end
+```
+
+### Project
+
+Retrieves all information for a specific Project. [Sample Response](https://docs.gathercontent.com/reference#get-project-by-id)
+
+```ruby
+require 'gather_content'
+
+project_id = 123456
+project = GatherContent::Api::Project.new(project_id)
+
+project["id"]
+=> 123456
+
+project["name"]
+=> "Example Project"
+```
+
+### Creating a Project
+
+Creates a new Project for a specific Account. When you create a Project, a default Workflow containing four Statuses will be created and associated with it. As part of this request a type can be passed as an argument to specify the project type.
+
+Supported project types
+
+* website-build
+* ongoing-website-content
+* marketing-editorial-content
+* email-marketing-content
+* other
+
+If successful, will return the newly created project.
+
+On failure, it will throw a GatherContent::Error::RequestError
+
+[Sample Response](https://docs.gathercontent.com/reference#post-projects)
+
+```ruby
+require 'gather_content'
+
+account_id = 123456
+
+begin
+  p = GatherContent::Api::Projects.new(account_id)
+  # Name is required. Type defaults to "other"
+  project = p.create{ "name" => "Project Name", "type" => "website-build" })
+
+  name = project["name"]
+rescue GatherContent::Error::RequestError => e
+  puts e.message
+end
+```
+
+### Statuses
+
+Retrieves a list of all the Statuses (what we call the Project’s Workflow) associated with a given Project. This includes their names, descriptions, associated colours and their Due Dates. [Sample Response](https://docs.gathercontent.com/reference#get-project-statuses)
+
+```ruby
+require 'gather_content'
+
+project_id = 123456
+statuses = GatherContent::Api::Statuses.new(project_id)
+
+statuses.each do |status|
+  puts status["id"]
+  puts status["name"]
+end
+```
+
+### Status
+
+Retrieves a list of all the Statuses (what we call the Project’s Workflow) associated with a given Project. This includes their names, descriptions, associated colours and their Due Dates. [Sample Response](https://docs.gathercontent.com/reference#get-project-statuses-by-id)
+
+```ruby
+require 'gather_content'
+
+status_id = 123456
+status = GatherContent::Api::Status.new(status_id)
+
+status["id"]
+=> 123456
+
+status["name"]
+=> "Draft"
+```
+
+## Items
+
+Get a list of all Items that exist on a particular Project.
+
+```ruby
+require 'gather_content'
+
+project_id = 123456
+items = GatherContent::Api::Items.new(project_id)
+
+items.each do |item|
+  puts item["id"]
+  puts item["name"]
+end
+```
+
+### Item
+
+Get all data related to a particular Item within a Project. You can access all of its properties, including the content which will be separated by the different fields it contains.
+
+```ruby
+require 'gather_content'
+
+item_id = 123456
+item = GatherContent::Api::Item.new(item_id)
+
+item["id"]
+=> 123456
+
+item["name"]
+=> "Home"
+```
+
+### Create an item
+
+Creates a new Item within a particular Project.
+
+The config object (if supplied) should be a Ruby Hash representation of the [configuration](https://docs.gathercontent.com/reference#the-config-field).
+
+If successful, will return the newly created item.
+
+On failure, it will throw a GatherContent::Error::RequestError
+
+```ruby
+require 'gather_content'
+
+project_id = 123456
+
+config = [{
+  "label": "Content",
+  "name": "tab1",
+  "hidden": false,
+  "elements": [{
+      "type": "text",
+      "name": "el1",
+      "required": false,
+      "label": "Blog post",
+      "value": "Hello world",
+      "microcopy": "",
+      "limit_type": "words",
+      "limit": 1000,
+      "plain_text": false
+  }]
+}]
+
+begin
+  i = GatherContent::Api::Items.new(project_id)
+  item = i.create({
+    "name" => "Item Name", # Required
+    "parent_id" => 123456, # Optional
+    "template_id" => 123456, # Optional
+    "config" => config, # Optional
+  });
+
+  puts item["name"]
+
+rescue GatherContent::Error::RequestError => e
+  puts e.message
+end
+```
+
+### Save an item
+
+Saves an Item with the newly updated data. It expects a valid configuration structure, otherwise the save request will not be accepted by the API.
+
+The config object should be a Ruby Hash representation of the [configuration](https://docs.gathercontent.com/reference#the-config-field).
+
+```ruby
+require 'gather_content'
+
+item_id = 123456
+item = GatherContent::Api::Item.new(item_id)
+
+config = [{
+  "label": "Content",
+  "name": "tab1",
+  "hidden": false,
+  "elements": [{
+      "type": "text",
+      "name": "el1",
+      "required": false,
+      "label": "Blog post",
+      "value": "Hello world",
+      "microcopy": "",
+      "limit_type": "words",
+      "limit": 1000,
+      "plain_text": false
+  }]
+}]
+
+begin
+  item.save(config)
+rescue GatherContent::Error::RequestError => e
+  puts e.message
+end
+```
+
+On failure, it will throw a GatherContent::Error::RequestError
+
+### Apply a template to an item
+
+Applies the structure of a Template to an existing Item.
+
+Beware that, just like within the application, this action will override the existing structure of an Item and may result in loss of content when fields do not match. Ensure you take necessary precautions.
+
+```ruby
+require 'gather_content'
+
+item_id = 123456
+item = GatherContent::Api::Item.new(item_id)
+
+template_id = 123456
+begin
+  item.apply_template(template_id)
+rescue GatherContent::Error::RequestError => e
+  puts e.message
+end
+```
+
+On failure, it will throw a GatherContent::Error::RequestError
+
+### Choose Status
+
+Set the status of the item
+
+```ruby
+require 'gather_content'
+
+item_id = 123456
+item = GatherContent::Api::Item.new(item_id)
+
+status_id = 123456
+begin
+  item.choose_status(status_id)
+rescue GatherContent::Error::RequestError => e
+  puts e.message
+end
+```
+
+On failure, it will throw a GatherContent::Error::RequestError
+
+### Files
+
+Get a list of all files related to a particular Item. [Sample Response](https://docs.gathercontent.com/reference#get-item-files)
+
+```ruby
+require 'gather_content'
+
+item_id = 123456
+files = GatherContent::Api::Files.new(item_id)
+
+files.each do |file|
+  puts file["id"]
+  puts file["filename"]
+end
+```
+
+## Templates
+
+Retrieves a list of all Templates associated with the given Project. [Sample Response](https://docs.gathercontent.com/reference#get-templates)
+
+```ruby
+require 'gather_content'
+
+project_id = 123456
+templates = GatherContent::Api::Templates.new(project_id)
+
+templates.each do |template|
+  puts template["id"]
+  puts template["name"]
+end
+```
+
+### Template
+
+This retrieves all data related with a specific Template. [Sample Response](https://docs.gathercontent.com/reference#get-template-by-id)
+
+```ruby
+require 'gather_content'
+
+template_id = 123456
+template = GatherContent::Api::Status.new(template_id)
+
+template["id"]
+=> 123456
+
+template["name"]
+=> "Blog theme"
+```

data/Rakefile

@@ -0,0 +1,14 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
+
+# Load up all rake tasks in lib/tasks
+Dir.glob('lib/tasks/*.rake').each { |r| import r }

data/gather_content-api.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gather_content/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "gather_content-api"
+  gem.version       = GatherContent::VERSION
+  gem.authors       = ["Barnaby Alter", "Hannan Butt"]
+  gem.email         = ["barnaby.alter@nyu.edu", "hab278@nyu.edu"]
+  gem.description   = %q{Ruby wrapper for the GatherContent API}
+  gem.summary       = %q{Ruby wrapper for the GatherContent API}
+  gem.homepage      = "https://github.com/NYULibraries/gather_content-api"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.licenses      = ['MIT']
+
+  gem.required_ruby_version = '>= 1.9.3'
+  gem.add_dependency 'rake', '~> 10'
+  gem.add_dependency 'rest-client', '~> 2'
+  gem.add_dependency 'faraday', '~> 0'
+end

data/lib/gather_content/api/account.rb

@@ -0,0 +1,25 @@
+module GatherContent
+  module Api
+    class Account < Base
+      attr_accessor :account_id
+
+      def initialize(account_id, data = nil)
+        raise ArgumentError, "account_id is required!" if account_id.nil?
+        @account_id = account_id
+        @data = data
+      end
+
+      def [](key)
+        fetch[key]
+      end
+
+    private
+
+      def path
+        @path ||= "/accounts/#{account_id}"
+      end
+
+      def params; end
+    end
+  end
+end

data/lib/gather_content/api/accounts.rb

@@ -0,0 +1,23 @@
+module GatherContent
+  module Api
+    class Accounts < Base
+      include Enumerable
+
+      def initialize; end
+
+      def each(&block)
+        fetch.each do |account|
+          yield GatherContent::Api::Account.new(account['id'], account)
+        end
+      end
+
+    private
+
+      def params; end
+
+      def path
+        @path ||= '/accounts'
+      end
+    end
+  end
+end

data/lib/gather_content/api/base.rb

@@ -0,0 +1,67 @@
+module GatherContent
+  module Api
+    class Base
+
+      def initialize
+        raise RuntimeError, "Cannot initialize this interface!"
+      end
+
+      def get(path_override = nil)
+        connection.get do |request|
+          request.url(path_override || path)
+          request.params = params unless params.nil?
+          request.headers['Accept'] = "application/vnd.gathercontent.v0.5+json"
+        end
+      end
+
+      def post(data = {}, path_override = nil)
+        connection.post do |request|
+          request.url(path_override || path)
+          request.body = data
+          request.headers['Accept'] = "application/vnd.gathercontent.v0.5+json"
+          yield request if block_given?
+        end
+      end
+
+      def post_json(data = {}, path_override = nil)
+        post(data.to_json, path_override) do |request|
+          request.headers['Content-type'] = "application/json"
+        end
+      end
+
+      def fetch
+        @data ||= parse(get.body)
+      end
+
+      def reset
+        @data = nil
+      end
+
+    protected
+      def params
+        raise RuntimeError, "Expected this to be implemented in a subclass!"
+      end
+
+      def path
+        raise RuntimeError, "Expected this to be implemented in a subclass!"
+      end
+
+    private
+      def parse(data)
+        parsed = JSON.parse(data)
+        parsed['data']
+      end
+
+      def connection
+        config = GatherContent::Api::Config.instance
+
+        @connection ||= Faraday.new(url: "#{config.host}:#{config.port}") do |faraday|
+          faraday.request  :url_encoded
+          faraday.request  :basic_auth, config.username, config.api_key
+          # faraday.response :logger
+          faraday.adapter  Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/gather_content/api/config.rb

@@ -0,0 +1,35 @@
+module GatherContent
+  module Api
+    class Config
+      attr_writer :username, :api_key, :host, :port
+
+      def self.run
+        yield self.instance
+      end
+
+      def self.instance
+        @instance ||= self.new
+      end
+
+      def username
+        @username || ENV['GATHER_CONTENT_API_USERNAME']
+      end
+
+      def api_key
+        @api_key || ENV['GATHER_CONTENT_API_KEY']
+      end
+
+      def host
+        @host || ENV['GATHER_CONTENT_API_HOST'] || "https://api.gathercontent.com"
+      end
+
+      def port
+        @port || ENV['GATHER_CONTENT_API_PORT'] || "443"
+      end
+
+    private
+      def initialize
+      end
+    end
+  end
+end

data/lib/gather_content/api/file.rb

@@ -0,0 +1,19 @@
+module GatherContent
+  module Api
+    class File < Base
+      attr_accessor :file_id
+
+      def initialize(item_id, file_id, data)
+        raise ArgumentError, "item_id is required!" if item_id.nil?
+        raise ArgumentError, "file_id is required!" if file_id.nil?
+        @item_id = item_id
+        @file_id = file_id
+        @data = data
+      end
+
+      def [](key)
+        @data[key]
+      end
+    end
+  end
+end

data/lib/gather_content/api/files.rb

@@ -0,0 +1,27 @@
+module GatherContent
+  module Api
+    class Files < Base
+      attr_accessor :item_id
+      include Enumerable
+
+      def initialize(item_id)
+        raise ArgumentError, "item_id is required!" if item_id.nil?
+        @item_id = item_id
+      end
+
+      def each(&block)
+      fetch.each do |file|
+        yield GatherContent::Api::File.new(@item_id, file['id'], file)
+      end
+    end
+
+    private
+
+      def path
+        @path ||= "/items/#{item_id}/files"
+      end
+
+      def params; end
+    end
+  end
+end