familysearch 0.2.0 → 0.3.0

data/.gitignore

@@ -0,0 +1,44 @@
+# rcov generated
+coverage
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkg
+
+workspace/*.rb
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+#.DS_Store
+#
+# For TextMate
+#*.tmproj
+#tmtags
+#
+# For emacs:
+#*~
+#\#*
+#.\#*
+#
+# For vim:
+#*.swp

data/Gemfile

@@ -1,20 +1,4 @@
 source "https://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
-gem 'faraday', "~> 0.8.4"
-gem 'faraday_middleware', "~> 0.9.0"
-gem 'multi_json', "~> 1.5.0"
-gem "hashie", "~> 1.2.0"
-gem "rash", "~> 0.3.2"
 
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
-group :development, :test do
-  gem "rspec", "~> 2.13.0"
-  gem "shoulda", "~> 3.3.2"
-  gem "bundler", "~> 1.2.3"
-  gem "jeweler", "~> 1.8.4"
-  gem "vcr", "~> 2.4.0"
-  gem "webmock", "~> 1.10.0"
-end
+# Specify your gem's dependencies in familysearch.gemspec
+gemspec

data/README.md

@@ -8,7 +8,7 @@ You can install it from the commandline.
 
 Or add it to a Gemfile for use with Bundler
 
-    gem "familysearch", "~> 0.1.0 "
+    gem "familysearch", "~> 0.3.0 "
 
 
 ## Basic Usage
@@ -20,21 +20,65 @@ Here's how to use it
     
     # Instantiate a Client object
     client = FamilySearch::Client.new :environment => :sandbox, :key => 'your-dev-key-here'
-    
-    # Load the Discovery resource
-    client.discover!
-    
+        
     # For testing, you can use basic auth to get a session, 
     # Don't do this in your production web app. Use OAuth 2.0
     client.basic_auth! 'your-username', 'your-password'
     
-    me = client.get(client.discovery.links.current_user_person.href).body
-    
-    # The response object is a Rash object (Hashie extension) which allows you to traverse via dot notation.
-    # It also allows an _ to be placed at the end of elements you are traversing to guard against nil values.
-    me.persons[0].display_.name
+    # the client object has a get, post, put, delete, and head method
+    response = client.get(client.discovery['links']['current-user-person']['href'])
+    response.status #=> 200
+	
+	# The response contains a Hash object on the body attribute.
+    response.body['persons'][0]['display']['name']
+
+## Discovery Resource
+
+The FamilySearch Platform is RESTful and conforms to HATEOAS principles. This means that you can discover addressable resources in the hypermedia that is returned by the platform. As a starting point, a Discovery Resource is offered up that lists resources that you can programatically begin to explore.
+
+The Discovery Resource is intended to be utilized heavily by this gem. One of the benefits of this is that if FamilySearch needs to change a URI for any resource, your application should continue to work because the URI will be updated in the discovery resource. URIs are not constructed by hard-coding paths within the gem. They are constructed by utilizing templates exposed via the Discovery Resource.
+
+### URL Templates
+
+The `familysearch` gem makes use of the templates exposed on the Discovery Resource. For example, the discovery resource exposes a person-template that looks like this:
+
+	"person-template" : {
+      "template" : "https://sandbox.familysearch.org/platform/tree/persons/{pid}{?access_token}",
+      "type" : "application/json,application/x-fs-v1+json,application/x-fs-v1+xml,application/x-gedcomx-v1+json,application/x-gedcomx-v1+xml,application/xml,text/html",
+      "accept" : "application/x-fs-v1+json,application/x-fs-v1+xml,application/x-gedcomx-v1+json,application/x-gedcomx-v1+xml",
+      "allow" : "HEAD,GET,POST,DELETE,GET,POST",
+      "title" : "Person"
+    }
+ 
+To utilize this template, you can do the following from your `client` object. 
+
+	response = client.template('person-template').get :pid => 'KWQS-BBQ'
+
+You can also use `'person'`, or `:person` instead of 'person-template'. The client will still find the appropriate template.
+
+The above code is equivalent to the following:
+
+	response = client.get 'https://sandbox.familysearch.org/platform/tree/persons/KWQX-52J'
+
+## Faraday
+
+This gem depends upon the wonderful `faraday` gem for handling HTTP calls. One of the advantages of this is that you could possibly swap out underlying http libraries. Currently, it utilizes the Net::HTTP library, but in the future it could potentially support other libraries such as EventMachine's asynchronous http library.
+
+## MultiJson
+
+This gem makes use of the awesome `multi_json` gem. This allows you to utilize faster json libraries if desired, such as `oj` or `yajil`. If you have `require`ed either of these libraries prior to requiring the `familysearch` gem, then it will make use of the faster JSON parsing libraries.
+
+## Future
+
+Next on the roadmap:
+
+* Support post, put, delete, head, etc. from the FamilySearch::URLTemplate objec. (currently only supports get)
+* Better object deserialization. Currently, everything is just a dumb Hash. I'd like to be able to allow an option to pass in another middleware for smarter objects (pershaps Hashie::Mash or Rash, or some sort of GedcomX model).
+* More documentation examples.
+
+## Bugs and Feature Requests
 
-More documentation coming soon...
+Please file bug reports and 
 
 ## Copyright
 

data/Rakefile

@@ -1,37 +1,17 @@
-require 'rubygems'
+$:.push File.expand_path("../lib", __FILE__)
+require "familysearch/version"
 require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-require 'rake'
-
-require 'jeweler'
-Jeweler::Tasks.new do |gem|
-  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "familysearch"
-  gem.homepage = "http://github.com/jimmyz/familysearch-rb"
-  gem.license = "MIT"
-  gem.summary = %Q{A gem for the FamilySearch Platform.}
-  gem.description = %Q{A gem for the FamilySearch Platform. Documentation for the FamilySearch Platform can be found at https://}
-  gem.email = "jimmy.zimmerman@gmail.com"
-  gem.authors = ["Jimmy Zimmerman"]
-  # Include your dependencies below. Runtime dependencies are required when using your gem,
-  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
-  #  gem.add_development_dependency 'rspec', '> 1.2.3'
-end
-Jeweler::RubygemsDotOrgTasks.new
+Bundler::GemHelper.install_tasks
 
 require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "-c"
+end
 task :default => :spec
 
 require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  version = FamilySearch::VERSION
 
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "familysearch #{version}"

data/familysearch.gemspec

@@ -1,87 +1,28 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "familysearch/version"
 
 Gem::Specification.new do |s|
-  s.name = "familysearch"
-  s.version = "0.2.0"
+  s.name        = "familysearch"
+  s.version     = FamilySearch::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Jimmy Zimmerman"]
+  s.email       = ["jimmy.zimmerman@gmail.com"]
+  s.homepage    = "https://github.com/jimmyz/familysearch-rb"
+  s.summary     = %q{A gem for the FamilySearch Platform.}
+  s.description = %q{A gem for the FamilySearch Platform. Documentation for the FamilySearch Platform can be found at https://familysearch.org/developers/.}
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Jimmy Zimmerman"]
-  s.date = "2013-03-19"
-  s.description = "A gem for the FamilySearch Platform. Documentation for the FamilySearch Platform can be found at https://"
-  s.email = "jimmy.zimmerman@gmail.com"
-  s.extra_rdoc_files = [
-    "LICENSE.txt",
-    "README.md"
-  ]
-  s.files = [
-    ".document",
-    ".rvmrc",
-    "Gemfile",
-    "LICENSE.txt",
-    "README.md",
-    "Rakefile",
-    "VERSION",
-    "familysearch.gemspec",
-    "lib/familysearch.rb",
-    "lib/familysearch/client.rb",
-    "spec/client_spec.rb",
-    "spec/familysearch_spec.rb",
-    "spec/fixtures/vcr_cassettes/discovery.yml",
-    "spec/fixtures/vcr_cassettes/discovery_auth.yml",
-    "spec/spec_helper.rb",
-    "workspace/notes/APIDesign.txt",
-    "workspace/notes/discovery_links.txt",
-    "workspace/notes/goals.txt"
-  ]
-  s.homepage = "http://github.com/jimmyz/familysearch-rb"
-  s.licenses = ["MIT"]
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.24"
-  s.summary = "A gem for the FamilySearch Platform."
-
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<faraday>, ["~> 0.8.4"])
-      s.add_runtime_dependency(%q<faraday_middleware>, ["~> 0.9.0"])
-      s.add_runtime_dependency(%q<multi_json>, ["~> 1.5.0"])
-      s.add_runtime_dependency(%q<hashie>, ["~> 1.2.0"])
-      s.add_runtime_dependency(%q<rash>, ["~> 0.3.2"])
-      s.add_development_dependency(%q<rspec>, ["~> 2.13.0"])
-      s.add_development_dependency(%q<shoulda>, ["~> 3.3.2"])
-      s.add_development_dependency(%q<bundler>, ["~> 1.2.3"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
-      s.add_development_dependency(%q<vcr>, ["~> 2.4.0"])
-      s.add_development_dependency(%q<webmock>, ["~> 1.10.0"])
-    else
-      s.add_dependency(%q<faraday>, ["~> 0.8.4"])
-      s.add_dependency(%q<faraday_middleware>, ["~> 0.9.0"])
-      s.add_dependency(%q<multi_json>, ["~> 1.5.0"])
-      s.add_dependency(%q<hashie>, ["~> 1.2.0"])
-      s.add_dependency(%q<rash>, ["~> 0.3.2"])
-      s.add_dependency(%q<rspec>, ["~> 2.13.0"])
-      s.add_dependency(%q<shoulda>, ["~> 3.3.2"])
-      s.add_dependency(%q<bundler>, ["~> 1.2.3"])
-      s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
-      s.add_dependency(%q<vcr>, ["~> 2.4.0"])
-      s.add_dependency(%q<webmock>, ["~> 1.10.0"])
-    end
-  else
-    s.add_dependency(%q<faraday>, ["~> 0.8.4"])
-    s.add_dependency(%q<faraday_middleware>, ["~> 0.9.0"])
-    s.add_dependency(%q<multi_json>, ["~> 1.5.0"])
-    s.add_dependency(%q<hashie>, ["~> 1.2.0"])
-    s.add_dependency(%q<rash>, ["~> 0.3.2"])
-    s.add_dependency(%q<rspec>, ["~> 2.13.0"])
-    s.add_dependency(%q<shoulda>, ["~> 3.3.2"])
-    s.add_dependency(%q<bundler>, ["~> 1.2.3"])
-    s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
-    s.add_dependency(%q<vcr>, ["~> 2.4.0"])
-    s.add_dependency(%q<webmock>, ["~> 1.10.0"])
-  end
-end
-
+  
+  s.add_dependency("faraday", ["~> 0.8.4"])
+  s.add_dependency("faraday_middleware", ["~> 0.9.0"])
+  s.add_dependency("multi_json", ["~> 1.5.0"])
+  s.add_development_dependency("rspec", ["~> 2.13.0"])
+  s.add_development_dependency("shoulda", ["~> 3.3.2"])
+  s.add_development_dependency("bundler", [">= 1.2.3"])
+  s.add_development_dependency("vcr", ["~> 2.4.0"])
+  s.add_development_dependency("webmock", ["~> 1.10.0"])
+end

data/lib/familysearch.rb

@@ -1 +1,2 @@
+require 'familysearch/version'
 require 'familysearch/client'

data/lib/familysearch/client.rb

@@ -1,10 +1,38 @@
-require 'hashie'
 require 'faraday'
 require 'faraday_middleware'
 require 'forwardable'
+require 'familysearch/url_template'
+require 'familysearch/error'
+require 'familysearch/middleware'
 
+# Namespace this gem functionality under FamilySearch. I realise it doesn't exactly follow gem conventions by CamelCasing FamilySearch,
+# but I'm just following FamilySearch branding (familysearch.org, not family_search.org and FamilySearch not Familysearch).
 module FamilySearch
+  # FamilySearch::Client is the core of the +familysearch+ gem. It manages the HTTP requests to
+  # the FamilySearch Platform. Under the covers, it is implemented using the wonderful Faraday ruby gem.
+  # 
+  # The +familysearch+ gem relies heavily on Faraday::Middleware features to handle such things such as
+  # following redirects, parsing JSON, logging HTTP traffic, and raising errors for non 20x or 30x responses.
+  # 
+  # =Usage:
+  # TODO: place some examples here.
+  # 
   class Client
+    # Contains a configuration for finding the discovery resource for the various systems.
+    #   {
+    #     :production => {
+    #      :base_url => 'https://familysearch.org',
+    #      :discovery_path => '/.well-known/app-meta'
+    #     },
+    #     :staging => {
+    #      :base_url => 'https://stage.familysearch.org',
+    #      :discovery_path => '/.well-known/app-meta'
+    #     },
+    #     :sandbox => {
+    #      :base_url => 'https://sandbox.familysearch.org',
+    #      :discovery_path => '/.well-known/app-meta'
+    #     }
+    #   }
     ENV_CONF = {
       :production => {
         :base_url => 'https://familysearch.org',
@@ -26,6 +54,22 @@ module FamilySearch
     extend Forwardable
     def_delegators :@agent, :get, :put, :post, :delete, :head, :options
     
+    # Initializing a FamilySearch::Client object.
+    # 
+    # *Args*    :
+    # - +options+: An Hash containing any of the following configuration items.
+    #   - +:key+: Your developer key.
+    #   - +:environment+: Accepts the following values: :production, :staging, :sandbox. 
+    #     It defaults to :sandbox.
+    #   - +:base_url+: If you would like to override the base url of the production, staging, 
+    #     or sandbox environments, you can set this to something else like "http://localhost:8080"
+    #   - +:access_token+: (optional) Your access token if you already have one.
+    #   - +:logger+: (optional) An object that conforms to the Logger interface. 
+    #     This could be a Rails logger, or another logger object that writes to 
+    #     STDOUT or to a file.
+    # *Returns* :
+    # - +FamilySearch::Client+: a client object for making requests
+    # 
     def initialize(options = {})
       @access_token = options[:access_token] # if options[:access_token]
       @logger = options[:logger]
@@ -33,27 +77,82 @@ module FamilySearch
       @environment = options[:environment] || :sandbox
       @base_url = options[:base_url] || ENV_CONF[@environment][:base_url]
       @agent = Faraday.new(@base_url) do |faraday|
+        faraday.response :familysearch_errors
         faraday.response :logger, options[:logger] if options[:logger]
-        faraday.response :rashify
-        faraday.response :json
+        faraday.response :multi_json
         faraday.response :follow_redirects, :limit => 3, :standards_compliant => true
         faraday.headers['Accept'] = 'application/x-fs-v1+json'
         faraday.authorization('Bearer',@access_token) if @access_token
         faraday.adapter  Faraday.default_adapter  # make requests with Net::HTTP
       end
     end
-        
+    
+    # This method gets information from the {Discovery Resource}[https://familysearch.org/.well-known/app-meta.json]. 
+    # 
+    # This call will cache the discovery resource in an attribute called @discovery. 
+    # 
+    # Calling this multiple times should be very cheap because of the caching. a FamilySearch::Client object will only
+    # ever make an HTTP request for the discovery resource *once* in its lifetime.
+    # 
+    # * *Returns* :
+    #   - +discovery+: the value of the @discovery attribute now that it has been populated.
+    # 
     def discover!
       @discovery ||= get_discovery
     end
     
+    # Performs an authentication against the /identity/v2/login resource. It uses the 
+    # {Discovery Resource}[https://familysearch.org/.well-known/app-meta.json] to determine the URL to make the request to
+    # in case the URL ever changes. This is only to be used for testing/development.
+    # 
+    # *Note*: You may *NOT* use this method for building web applications. All web applications must use OAuth/OAuth2.
+    # Your web application will not be certified if it prompts for user credentials within the application. Also, you may not use
+    # your personal credentials to authenticate your system in behalf of a user.
+    # 
+    # *Args*    :
+    # - +username+: A FamilySearch username.
+    # - +password+: The user's password.
+    # - +key+ (optional): Your developer key if it wasn't already set when you initialized the FamilySearch::Client
+    # *Returns* :
+    # - true
+    # *Raises*  :
+    # - +FamilySearch::Error::BadCredentials+: If it cannot authenticate
+    # 
     def basic_auth!(username,password,key=nil)
       self.discover!
       @key ||= key if key
       @agent.basic_auth username, password
-      response = @agent.get @discovery.links.fs_identity_v2_login.href, :dataFormat => 'application/json', :key => @key
-      @access_token = response.body.session.id
+      response = @agent.get @discovery['links']['fs-identity-v2-login']['href'], :dataFormat => 'application/json', :key => @key
+      @access_token = response.body['session']['id']
       @agent.authorization('Bearer',@access_token)
+      return true
+    end
+    
+    # Used for taking advantage of URL templates provided by the {Discovery Resource}[https://familysearch.org/.well-known/app-meta.json].
+    # 
+    # This method will automatically call the FamilySearch::Client#discover! method in order to populate the discovery resources.
+    # 
+    # ===Usage:
+    # 
+    #   client = FamilySearch::Client.new
+    #   res = client.template('person').get :pid => 'KWQS-BBQ'
+    #   res.body['persons'][0]['id] # => 'KWQS-BBQ'
+    # 
+    # Please note, only the +get+ method has been implemented on the URLTemplate object. POST, PUT, and DELETE should be pretty easy
+    # to add. It just hasn't been a priority yet.
+    # 
+    # *Args*    :
+    # - +template_name+: The name of the template. For the "person-template", you can pass "person-template", "person", or :person
+    # *Returns* :
+    # - FamilySearch::URLTemplate object
+    # *Raises*  :
+    # - +FamilySearch::Error::URLTemplateNotFound+: if the template is not found.
+    # 
+    def template(template_name)
+      self.discover!
+      k = template_name.to_s
+      template = @discovery['links'][k] || @discovery['links'][k+'-template'] || @discovery['links'][k+'-query']
+      FamilySearch::URLTemplate.new self, template
     end
     
     private