Project

scaleapi-ruby

0.01

Repository is archived

No commit activity in last 3 years

No release in over 3 years

scaleapi-ruby wikiti/scaleapi-ruby Homepage Documentation Source Code Bug Tracker Wiki

A ruby gem wrapper for the Scale API, containing all the endpoints available.

2005

2006

2007

2008

2009

2010

2011

2012

2013

2014

2015

2016

2017

2018

2019

2020

2021

2022

2023

2024

Popularity

231,528

5

0

2

Releases

Current version

0.3.0

5

2016-09-21

2017-02-20

Issues

0

2

2

Issue Closure Rate

100%

Development

Primary Language

Ruby

Licenses

MIT

Average date of last 50 commits

2016-11-21

Reverse Dependencies

0

Dependencies

Development

~> 1.0

~> 2.1.0

pry

>= 0

>= 0

rdoc

~> 3.12

Runtime

activesupport

>= 0

rest-client

>= 0

Project Readme

THIS PROJECT IS NO LONGER MAINTAINED. USE THE OFFICIAL GEM INSTEAD

ScaleAPI for Ruby

A simple ruby wrapper for the Scale HTTP API. Documentation for this API is available here.

This project uses juwelier for managing and releasing this gem.

Installation

Add this line to your application's Gemfile:

gem 'scaleapi-ruby'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install scaleapi-ruby

Usage

First, you need to initialize the Scale client:

require 'scale'
scale = Scale.setup api_key: 'YOUR_KEY_GOES_HERE',              # Required
                    callback_key: 'YOUR CALLBACK_KEY_GOES_HERE' # Optional

Check this for further information.

Tasks

Most of these methods will return a Scale::Resources::Task object, which will contain information about the json response (task_id, status...).

Any parameter available in the documentation can be passed as an argument option with the corresponding type.

The following endpoints for tasks are available:

Create categorization task

Check this for further information.

task = scale.create_categorization_task(
  callback_url: 'http://www.example.com/callback',
  instruction: 'Is this company public or private?',
  attachment_type: 'website',
  attachment: 'http://www.google.com/',
  categories: ['public', 'private']
)

Create transcription task

Check this for further information.

task = scale.create_transcription_task(
  callback_url: 'http://www.example.com/callback',
  instruction: 'Transcribe the given fields. Then for each news item on the page, transcribe the information for the row.',
  attachment_type: 'website',
  attachment: 'http://www.google.com/',
  fields: { title: 'Title of Webpage', top_result: 'Title of the top result' },
  row_fields: { username: 'Username of submitter', comment_count: 'Number of comments' }
)

Create phone call task

Check this for further information.

scale.create_phonecall_task(
  callback_url: 'http://www.example.com/callback',
  instruction: "Call this person and tell me his email address. Ask if he's happy too.",
  phone_number: '5055006865',
  entity_name: 'Alexandr Wang',
  script: 'Hello ! Are you happy today? (pause) One more thing - what is your email address?',
  fields: { email: 'Email Address' },
  choices: ['He is happy', 'He is not happy']
)

Create comparison task

Check this for further information.

scale.create_comparison_task(
  callback_url: 'http://www.example.com/callback',
  instruction: 'Do the objects in these images have the same pattern?',
  attachment_type: 'image',
  choices: ['yes', 'no'],
  attachments: [
    'http://i.ebayimg.com/00/$T2eC16dHJGwFFZKjy5ZjBRfNyMC4Ig~~_32.JPG',
    'http://images.wisegeek.com/checkered-tablecloth.jpg'
  ]
)

Create annotation task

Check this for further information.

scale.create_annotation_task(
  callback_url: 'http://www.example.com/callback',
  instruction: 'Draw a box around each baby cow and big cow.',
  attachment_type: "image",
  attachment: "http://i.imgur.com/v4cBreD.jpg",
  objects_to_annotate: ["baby cow", "big cow"],
  examples: [
    {
      correct: false,
      image: 'http://i.imgur.com/lj6e98s.jpg',
      explanation: 'The boxes are tight and accurate'
    },
    {
      correct: true,
      image: 'http://i.imgur.com/HIrvIDq.jpg',
      explanation: 'The boxes are neither accurate nor complete'
    }
  ]
)

Create data collection task

Check this for further information.

scale.create_data_collection_task(
  callback_url: 'http://www.example.com/callback',
  instruction: 'Find the URL for the hiring page for the company with attached website.',
  attachment_type: 'website',
  attachment: 'https://www.scaleapi.com/',
  fields: {
    hiring_page: 'Hiring Page URL'
  }
)

Retrieve task

Check this for further information.

Retrieve a task given its id.

task = scale.retrieve_task 'asdfasdfasdfasdfasdfasdf'
task.id == 'asdfasdfasdfasdfasdfasdf' # true

Cancel task

Check this for further information.

Cancel a task given its id, only if it's not completed.

task = scale.cancel_task 'asdfasdfasdfasdfasdfasdf'

List tasks

Check this for further information.

Retrieve a list (Array) of all tasks.

tasks = scale.tasks # Scale::Resources::Tasks
tasks.all? { |t| t.is_a? Scale::Resources::Task } # true

Callbacks

This gem allows you to create and parse callback data, so it can be easily used for web applications:

For example, for Ruby on Rails:

# app/controllers/scale_api_controller.rb
class ScaleApiController < ApplicationController
  # POST /scale_api
  def create
    callback = scale.build_callback params, 'task', callback_key: request.headers['scale-callback-auth']
    callback.response # Response content hash (code and result)
    callback.task     # Scale::Resources::Task object
  end
end

Please note that callback validation is optional; omit it if no callback_key was passed to Scale.build builder.

If the validation is enabled, the build_callback method will raise a Scale::GenericError, explaning that the tokens don't match. You can also use valid_callback_key? to test it:

# `scale.callback_key` is 'TEST'
scale.valid_callback_key? 'FAKE' # false, because 'TEST' != 'FAKE'

Error handling

If something went wrong while making API calls, then exceptions will be raised automatically as a Scale::GenericError (or Scale::HttpError) runtime error. For example:

begin
  scale.create_categorization_task instructions: 'Some parameters are missing.'
rescue Scale::HttpError => e
  puts e.code # 400
  puts e.exception # Missing parameter X
  pust e.original_exception # Catched exception
rescue Scale::GenericError => e
  puts e.message # Missing parameter X
end

Custom options

The api initialization accepts the following options:

Name	Description	Default
`endpoint`	Endpoint used in the http requests.	`'https://api.scaleapi.com/v1/'`
`api_key`	API key used in the http requests.	`nil`
`callback_key`	API key used to validate callback POST requests.	`nil`
`default_request_params`	Default parameters (payload) for the API requests	`{}`

For example, default_request_params can be used to always set the same callback_url value:

scale = Scale.setup api_key: 'YOUR_KEY_GOES_HERE',              # Required
                    callback_key: 'YOUR CALLBACK_KEY_GOES_HERE' # Optional
                    default_request_params: {
                      callback_url: 'http://www.example.com/callback'
                    }

# All callback requests will posted be made to http://www.example.com/callback
scale.create_comparison_task(
  instruction: 'Draw a box around each baby cow and big cow.',
  attachment_type: "image",
  attachment: "http://i.imgur.com/v4cBreD.jpg",
  objects_to_annotate: ["baby cow", "big cow"]
)

Development

Clone this repository with:

$ git clone https://github.com/wikiti/scaleapi-ruby
$ cd scaleapi-ruby

Install the current development version as a gem with:

$ rake install

Run tests with:

$ SCALE_API_KEY="your_scale_api_key" rake test

Authors

This project has been developed by:

Avatar	Name	Nickname	Email
	Daniel Herzog	Wikiti	wikiti.doghound@gmail.com