Fulcrum

Fulcrum API Gem

• Ruby 1.9.3+
• Fulcrum account

Add this line to your application's Gemfile:

gem 'fulcrum'

And then execute:

bundle

Or install it yourself as:

gem install fulcrum

Most interaction with the API is done through a client object. Below is a simple example of how to instantiate a client object.

client = Fulcrum::Client.new(your_api_key)

A client object assumes you have an API key. To get an API key use the get_user and create_authorization class methods.

Fulcrum::Client.get_user(email, password)
# returns a user's name, email, avatar url, and a list of organizations with ids for creating authorizations

Fulcrum::Client.create_authorization(email, password, org_id, note, timeout = nil, user_id = nil)
# creates an authorization for yourself or another user in the provided organization id

In general, this API is intended to be a low level wrapper around the Fulcrum API. All of the filtering and query parameters are passed directly through to the HTTP request. It's best to read the API documentation to get a sense of the parameters available for each resource. Resource instances are returned from the API as simple hashes.

When using the create or update methods on resources, the object passed to the method should be in the same format as a result from calling find on that resource. For example, you can call client.records.find(id) and the result can be used as the parameter for client.records.update(id, record).

Each of the API resources has an all method that can be used to fetch a list of resources. The all methods accept some basic pagination parameters (per_page and page) you can use to iterate over the pages. Because the index API's are paginated, the result of all is not the objects themselves. The all methods return a Page object that has some basic attributes to inspect the pagination extents. The objects attribute returns the actual array of objects. Below is a simple example that fetches the first page of records from the API.

client = Fulcrum::Client.new(your_api_key)

result = client.records.all(form_id: my_form_id, page: 1, per_page: 100)

puts result.class         # Fulcrum::Page
puts result.per_page      # => 100
puts result.current_page  # => 1
puts result.total_pages   # => 2
puts result.total_count   # => 137
puts result.objects.count # => 100
puts result.objects       # [ ... the records ... ]

Retrieve records with optional parameters. For a full list of the available parameters, see the API documentation.

client.records.all(page: 1, per_page: 100, form_id: some_form_id, updated_since: timestamp)

Find a single record by its id and return a Hash of the record attributes.

Create a new record from a Hash of attributes. The format of the attributes is identical to the format returned from find. The record API documentation has more information on the format. Note: although the raw API uses a hash wrapped in a record attribute, this is not necessary for the ruby API. Instead of { "record" => record_attributes }, you simply pass record_attributes directly to this method.

Update an existing record by its id using a Hash of attributes. The format of the attributes is identical to the format returned from find. The record API documentation has more information on the format. Note: although the raw API uses a hash wrapped in a record attribute, this is not necessary for the ruby API. Instead of { "record" => record_attributes }, you simply pass record_attributes directly to this method.

Delete a record by its id. This method optionally accepts a changeset_id to group deletes into a Changeset for compatibility with the activity feed.

Find a record's history by its id.

Create a new photo from a file or a file path. attributes must be a Hash and currently only accepts 1 attribute, access_key. If you specify an access_key, it must be a UUID. If you don't specify an access_key, one will be automatically generated and returned in the response.

Downloads the original version and yields an IO object to the block. The block is passed an IO object that you can call #read on. For example, to download a photo to a file:

client.photos.original(id) do |input|
  File.open('output.jpg', 'wb') do |output|
    output.write(input.read)
  end
end

Downloads the thumbnail version and yields an IO object to the block.

Downloads the large version and yields an IO object to the block.

Create a new signature from a file or a file path. attributes must be a Hash and currently only accepts 1 attribute, access_key. If you specify an access_key, it must be a UUID. If you don't specify an access_key, one will be automatically generated and returned in the response.

Downloads the original version and yields an IO object to the block.

Downloads the thumbnail version and yields an IO object to the block.

Downloads the large version and yields an IO object to the block.

Create a new video from a file or a file path. attributes must be a Hash and currently only accepts 2 attributes, access_key and track. If you specify an access_key, it must be a UUID. If you don't specify an access_key, one will be automatically generated and returned in the response.

Downloads the original version and yields an IO object to the block.

Downloads the small version and yields an IO object to the block.

Downloads the medium version and yields an IO object to the block.

Fetches the GPS track for the specified video.

Format can be 'json', 'geojson', 'gpx', or 'kml'.

Create a new audio object from a file or a file path. attributes must be a Hash and currently only accepts 2 attributes, access_key and track. If you specify an access_key, it must be a UUID. If you don't specify an access_key, one will be automatically generated and returned in the response.

Downloads the original version and yields an IO object to the block.

Downloads the small version and yields an IO object to the block.

Downloads the medium version and yields an IO object to the block.

Fetches the GPS track for the specified audio.

Format can be 'json', 'geojson', 'gpx', or 'kml'.

Suggestion pass a File.open(file) to this as parameter

Fetches a Query API response for various formats for a provided SQL string.

Format can be 'json', 'csv', or 'geojson'.

• Fulcrum REST API
• Fulcrum Query API

1. Fork the repo
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request