Class: Veritable::API

Inherits:
Object
  • Object
show all
Includes:
VeritableResource
Defined in:
lib/veritable/api.rb

Overview

Represents the resources available to a user of the Veritable API.

Users should not initialize directly; use Veritable.connect as the entry point.

Methods

  • root -- gets the root of the API
  • limits -- gets the user-specific API limits
  • tables -- gets a Veritable::Cursor over the collection of available tables
  • table -- gets an individual data table by its unique id
  • create_table -- creates a new data table
  • delete_table -- deletes a new data table by its unique id
  • has_table? -- checks whether a table with the given id is available

See also: https://dev.priorknowledge.com/docs/client/ruby

Instance Method Summary collapse

Methods included from Connection

#delete, #get, #post, #put, #request

Constructor Details

#initialize(opts = nil, doc = nil) ⇒ API

Returns a new instance of API.



27
28
29
30
 
# File 'lib/veritable/api.rb', line 27

def initialize(opts=nil, doc=nil)
  super
  @opts['api_limits'] = get("user/limits")
end

Instance Method Details

#create_table(table_id = nil, description = '', force = false) ⇒ Object

Creates a new table

Arguments

  • table_id -- the unique String id of the new table. Must contain only alphanumeric characters, underscores, and dashes. Note that underscores and dashes are not permitted as the first character of a table_id. Default is nil, in which case a new id will be automatically generated.
  • description -- a String describing the table. Default is ''.
  • force -- if true, will overwrite any existing table with the same id. Default is false.

Raises

A Veritable::VeritableError if force is not true and there is an existing table with the same id.

Returns

A Veritable::Table

See also: https://dev.priorknowledge.com/docs/client/ruby



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/veritable/api.rb', line 92

def create_table(table_id=nil, description='', force=false)
  if table_id.nil?
    autogen = true
    table_id = Util.make_table_id
  else
    autogen = false
    Util.check_id table_id
  end

  if has_table? table_id
    if autogen
      return create_table(nil, description, false)
    end
    if ! force
      raise VeritableError.new("Couldn't create table -- table with id #{table_id} already exists.")
    else
      delete_table table_id
    end
  end
  doc = post("tables", {:_id => table_id, :description => description})
  Table.new(@opts, doc)
end

#delete_table(table_id) ⇒ Object

Deletes an existing table

Arguments

table_id --- the unique id of the table to delete

Returns

nil on success. Succeeds silently if no table with the specified id is found.

See also: https://dev.priorknowledge.com/docs/client/ruby



124
 
# File 'lib/veritable/api.rb', line 124

def delete_table(table_id); delete("tables/#{table_id}"); nil; end

#has_table?(table_id) ⇒ Boolean

Checks if a table with the given unique id exists

Arguments

table_id --- the unique id of the table to check

Returns

true or false, as appropriate.

See also: https://dev.priorknowledge.com/docs/client/ruby

Returns:

  • (Boolean) 


135
136
137
138
139
140
141
142
143
 
# File 'lib/veritable/api.rb', line 135

def has_table?(table_id)
  begin
    table table_id
  rescue
    false
  else
    true
  end
end

#inspect ⇒ Object

Returns a string representation of the API resource



146
 
# File 'lib/veritable/api.rb', line 146

def inspect; to_s; end

#limits ⇒ Object

Gets the user-specific API limits

Returns

A Hash representing the user's current API limits.

See also: https://dev.priorknowledge.com/docs/client/ruby



46
47
48
 
# File 'lib/veritable/api.rb', line 46

def limits
    return @opts['api_limits']
end

#root ⇒ Object

Gets the root of the api

Returns

A Hash with the keys "status" (should be equal to "SUCCESS") and "entropy" (a random Float).

See also: https://dev.priorknowledge.com/docs/client/ruby



38
 
# File 'lib/veritable/api.rb', line 38

def root; get(""); end

#table(table_id) ⇒ Object

Gets an individual table by its unique id

Arguments

  • table_id -- the unique id of the table

Returns

A Veritable::Table

See also: https://dev.priorknowledge.com/docs/client/ruby



76
 
# File 'lib/veritable/api.rb', line 76

def table(table_id); Table.new(@opts, get("tables/#{table_id}")); end

#tables(opts = {'start' => nil, 'limit' => nil}) ⇒ Object

Gets a cursor for the table collection

Arguments

  • opts A Hash optionally containing the keys
    • "start" -- the table id from which the cursor should begin returning results. Defaults to nil, in which case the cursor will return result starting with the lexicographically first table id.
    • "limit" -- the total number of results to return (must be a Fixnum). Defaults to nil, in which case the number of results returned will not be limited.

Returns

A Veritable::Cursor. The cursor will return Veritable::Table objects representing the available data tables, in lexicographic order of their unique ids.

See also: https://dev.priorknowledge.com/docs/client/ruby



61
62
63
64
65
 
# File 'lib/veritable/api.rb', line 61

def tables(opts={'start' => nil, 'limit' => nil})
  Cursor.new({'collection' => "tables",
    'start' => opts['start'],
    'limit' => opts['limit']}.update(@opts)) {|x| Table.new(@opts, x)}
end

#to_s ⇒ Object

Returns a string representation of the API resource



149
 
# File 'lib/veritable/api.rb', line 149

def to_s; "#<Veritable::API url='#{api_base_url}'>"; end