Class: FamilySearch::URLTemplate

Inherits:
Object
  • Object
show all
Defined in:
lib/familysearch/url_template.rb

Overview

Used to make calls on templates that are exposed through the Discovery Resource.

It wouldn’t be expected that a developer would access this class directly, but is the resulting object of a FamilySearch::Client#template call.

Usage:

To use the URLTemplate, access the template from the FamilySearch::Client object like so:

client = FamilySearch::Client.new
res = client.template('person').get :pid => 'KWQS-BBQ'
res.body['persons'][0]['id] # => 'KWQS-BBQ'

For information on which templates are available, see the discovery resource.

sandbox

sandbox.familysearch.org/.well-known/app-meta.json

production

familysearch.org/.well-known/app-meta.json

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client, template_hash) ⇒ URLTemplate

Instantiate a new FamilySearch::URLTemplate

Args :

  • client: a FamilySearch::Client object.

  • template_hash: a hash containing template values from the Discovery Resource. Example:

    {
  "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"
}

Returns :

  • FamilySearch::URLTemplate object

Raises :

  • FamilySearch::Error::URLTemplateNotFound: if the template_hash is nil. This is intended to catch problems if FamilySearch::Client#template method doesn’t find a template and still instantiates this object.

Raises:



45
46
47
48
49
50
51
52
53
 
# File 'lib/familysearch/url_template.rb', line 45

def initialize(client,template_hash)
  raise FamilySearch::Error::URLTemplateNotFound if template_hash.nil?
  @client = client
  @template = template_hash['template']
  @type = template_hash['type']
  @accept = template_hash['accept']
  @allow = template_hash['allow'].split(',').map{|v|v.downcase}
  @title = template_hash['title']
end

Instance Attribute Details

#accept ⇒ Object (readonly)

Returns the value of attribute accept.



23
24
25
 
# File 'lib/familysearch/url_template.rb', line 23

def accept
  @accept
end

#allow ⇒ Object (readonly)

Returns the value of attribute allow.



23
24
25
 
# File 'lib/familysearch/url_template.rb', line 23

def allow
  @allow
end

#template ⇒ Object (readonly)

Returns the value of attribute template.



23
24
25
 
# File 'lib/familysearch/url_template.rb', line 23

def template
  @template
end

#title ⇒ Object (readonly)

Returns the value of attribute title.



23
24
25
 
# File 'lib/familysearch/url_template.rb', line 23

def title
  @title
end

#type ⇒ Object (readonly)

Returns the value of attribute type.



23
24
25
 
# File 'lib/familysearch/url_template.rb', line 23

def type
  @type
end

Instance Method Details

#get(template_values) ⇒ Object

Calls HTTP GET on the URL template. It takes the template_values hash and merges the values into the template.

A template will contain a URL like this:

https://sandbox.familysearch.org/platform/tree/persons-with-relationships{?access_token,person}

or

https://sandbox.familysearch.org/platform/tree/persons/{pid}/matches{?access_token}

The ?person type attributes in the first example will be passed as querystring parameters. These will automatically be URL Encoded by the underlying Faraday library that handles the HTTP request.

The pid type attibutes will simply be substituted into the URL.

Note: The access_token parameter doesn’t need to be passed here. This should be handled by the FamilySearch::Client’s Authorization header.

Args :

  • template_values: A Hash object containing the values for the items in the URL template. For example, if the URL is:

    https://sandbox.familysearch.org/platform/tree/persons-with-relationships{?access_token,person}

    then you would pass a hash like this:

    :person => 'KWQS-BBQ'

    or

    'person' => 'KWQS-BBQ'

Returns :

  • Faraday::Response object. This object contains methods body, headers, and status. body should contain a Hash of the parsed result of the request.

Raises :

  • FamilySearch::Error::MethodNotAllowed: if you call get for a template that doesn’t allow GET method.

Raises:



83
84
85
86
87
88
89
 
# File 'lib/familysearch/url_template.rb', line 83

def get(template_values)
  raise FamilySearch::Error::MethodNotAllowed unless allow.include?('get')
  template_values = validate_values(template_values)
  t = Addressable::Template.new(@template)
  url = t.expand(template_values).to_s
  @client.get url
end