Skip to content

Instantly share code, notes, and snippets.

@solso
Created May 9, 2012 15:09
Show Gist options
  • Save solso/2645294 to your computer and use it in GitHub Desktop.
Save solso/2645294 to your computer and use it in GitHub Desktop.
Active Docs for the Sentiment API (based on the Swagger specification)
#!/usr/bin/env ruby
require 'rubygems'
require 'json'
require 'sinatra'
require './analyzer.rb'
class SentimentApi < Sinatra::Base
disable :logging
disable :raise_errors
disable :show_exceptions
configure :production do
disable :dump_errors
end
set :server, 'thin'
@@the_logic = Analyzer.new
##~ sapi = source2swagger.namespace("sentiment_api_v1")
##~ sapi.basePath = "http://api-sentiment.3scale.net"
##~ sapi.apiVersion = "v1"
##
## -- Parameters
##~ @par_app_id = {:name => "app_id", :description => "Your access application id", :dataType => "string", :paramType => "query", :threescale_name => "app_ids"}
##~ @par_app_key = {:name => "app_key", :description => "Your access application key", :dataType => "string", :paramType => "query", :threescale_name => "app_keys"}
##
##~ a = sapi.apis.add
##~ a.set :path => "/v1/word/{word}.json"
##~ op = a.operations.add
##~ op.set :httpMethod => "GET"
##~ op.summary = "Returns the sentiment value of a given word"
##~ op.description = "<p>This operation returns the sentiment value on a scale from -5 to +5 of the given word.<p>For instance, the word \"awesome\" returns {\"word\":\"awesome\",\"sentiment\":4} with a positive connotation whereas \"damnit\" is less positive {\"word\":\"damnit\",\"sentiment\":-4}"
##~ op.group = "words"
##~ op.parameters.add :name => "word", :description => "The word whose sentiment is returned", :dataType => "string", :required => true, :paramType => "path"
##~ op.parameters.add @par_app_id
##~ op.parameters.add @par_app_key
##
get '/v1/word/:word.json' do
res = @@the_logic.word(params[:word])
content_type 'application/json'
body res.to_json
status 200
end
##~ op = a.operations.add
##~ op.set :httpMethod => "POST"
##~ op.summary = "Sets the sentiment value of a given word"
##~ op.description = "<p>This operation allows you to set the sentiment value to a word.<p>The sentiment value needs to be on the range -5 to +5."
##~ op.group = "words"
##~ op.parameters.add :name => "word", :description => "The word whose sentiment is returned", :dataType => "string", :required => true, :paramType => "path"
##~ op.parameters.add :name => "value", :description => "The sentiment value of the word, must be -5 to -1 for negative or to +1 to +5 for positive connotations", :allowableValues => {:values => ["-5","-4","-3","-2","-1","1","2","3","4","5"], :valueType => "LIST"}, :dataType => "string", :required => true, :defaultValue => "1", :paramType => "query"
##~ op.parameters.add @par_app_id
##~ op.parameters.add @par_app_key
##
post '/v1/word/:word.json' do
res = @@the_logic.add_word(params[:word],params[:value])
content_type 'application/json'
body res.to_json
status 200
end
##~ a = sapi.apis.add
##~ a.set :path => "/v1/sentence/{sentence}.json"
##~ op = a.operations.add
##~ op.set :httpMethod => "GET"
##~ op.summary = "Returns the aggregated sentiment of a sentence"
##~ op.description = "<p>This operation returns the aggregated value of a sentence based on the individual sentiment values of the words of the sentence.<p>The result for \"3scale rocks\" would be {\"sentence\":\"3scale rocks\",\"count\":2,\"certainty\":0.5,\"sentiment\":4.0}, overall sentiment of 4 in a -5 to +5 scale with certainty of 50% because only one word had a defined sentiment value."
##~ op.group = "sentence"
##~ op.parameters.add :name => "sentence", :description => "The sentence to be analyzed", :dataType => "string", :required => true, :paramType => "path"
##~ op.parameters.add @par_app_id
##~ op.parameters.add @par_app_key
##
get '/v1/sentence/:sentence.json' do
res = @@the_logic.sentence(params[:sentence])
content_type 'application/json'
body res.to_json
status 200
end
not_found do
""
end
error InvalidParameters do
error_code = 422
content_type 'application/json'
error error_code, {:error => {:reason => env['sinatra.error'].to_s, :code => error_code}}.to_json
end
error do
error_code = 500
content_type 'application/json'
error error_code, {:error => {:reason => env['sinatra.error'].to_s, :code => error_code}}.to_json
end
end
SentimentApi.run! :port => ARGV[0]
{
"path": "/sentence/{sentence}.json",
// The path to the resource, each $API has a unique path. Note that the values
// between brackets mean parameters, more exactly parameters of type "path".
"operations": [$OPERATION],
// The operations is a list of $OPERATION, which corresponds to an http verb
// on the resource path. For instance, GET, POST, PUT, DELETE, OPTIONS, etc.
"description": "Description",
// This description is not displayed anywhere, just for internal use
"errorResponses": [$ERROR]
// The list of $ERROR that contain a description of the possible errors on
// the resource. Declaring the errors is not mandatory for the interactive UI.
// However, if you plan to generate client-side libraries using Swagger’s Code
//Generators you must declare them.
}
"parameters": [
{
"name": "app_id",
"dataType": "string",
"threescale_name": "app_ids",
// "threescale_name": "app_ids" for authentication model App Id or OAuth
// or "threescale_name": "app_keys" for authentication mode APP Id
// or "threescale_name": "user_keys" for authentication model API Key
...
},
...
]
{
"basePath": "http://api-sentiment.3scale.net",
// The basePath is the end-point of your API. Not the Developer
// or the Admin Portal but the endpoint that serves your API requests.
"swagrVersion": "0.1a",
// the version of Swagger
"apiVersion": "1.0",
// the version of your API
"apis": [$API],
// And $API corresponds to a resource on your RESTful API, a path
// if you will. In the sentiment_api_v1.json there are 2, one for /v1/word/{word}.json
// and one for /v1/sentence/{sentence}.json
"models": [$MODEL]
// The $MODEL corresponds to the specification of the model objects
// of your API, for instance, user, account, word, etc. Models are not
// used on the interactive UI so they are not required, unless you also
// want to generate client-side libraries using Swagger’s Code Generators.
// In that case, you will have to declare the models too.
}
{
"reason": "\"word\" is not a single word"
// The error description
"code": 422
// HTTP Status Response Code
}
{
// The $OPERATION is what is shown as a bar-like container in the interactive UI.
"httpMethod": "GET",
// The http verb of the operation,
"summary": "Returns the aggregated sentiment of a sentence",
// The summary of the operation, the text that is displayed on the bar-like container,
// it is advisable to be short otherwise will not fit.
"description:": "<p>This operation returns the aggregated value of a sentence based on the individual sentiment values of the words of the sentence.<p>The...",
// The description is displayed once the bar-like container is clicked.
"group": "sentence",
// Group is a field specific to 3scale's Active Docs and not part of the
// Swagger spec. It is used to group operations by colors so that related
// operations (defined by the value of the string) appear on the same color.
// In the case of the sentiment_api_v1.json we use two: "sentence" and "word",
// so that a different color scheme is applied on the bar-like containers that
// represent the operations.
"parameters": [$PARAMETER]
// Parameters of the operation. This is the list of the parameters that are also defined
// as objects.
}
{
"name": "word",
// The name of the parameter name
"description": "The word whose sentiment is returned",
// Description of the parameter. This description is displayed in the interactive UI.
"dataType": "string",
// The dataType of the parameter. More on this further down.
"required": true,
// If not present defaults to false.
"paramType": "path",
// "path" is for when the parameter is part of the URL path (e.g /foo/ID.xml)
// "query" is for when the parameter is part of the query_string or a form
// (e.g. /foo.xml?ID=VALUE)
}
{
"basePath": "http://api-sentiment.3scale.net",
"apiVersion": "v1",
"apis": [
{
"path": "/v1/word/{word}.json",
"operations": [
{
"httpMethod": "GET",
"summary": "Returns the sentiment value of a given word",
"description": "<p>This operation returns the sentiment value on a scale from -5 to +5 of the given word.<p>For instance, the word \"awesome\" returns {\"word\":\"awesome\",\"sentiment\":4} with a positive connotation whereas \"damnit\" is less positive {\"word\":\"damnit\",\"sentiment\":-4}",
"group": "words",
"parameters": [
{
"name": "word",
"description": "The word whose sentiment is returned",
"dataType": "string",
"required": true,
"paramType": "path"
},
{
"name": "app_id",
"description": "Your access application id",
"dataType": "string",
"paramType": "query",
"threescale_name": "app_ids"
},
{
"name": "app_key",
"description": "Your access application key",
"dataType": "string",
"paramType": "query",
"threescale_name": "app_keys"
}
]
},
{
"httpMethod": "POST",
"summary": "Sets the sentiment value of a given word",
"description": "<p>This operation allows you to set the sentiment value to a word.<p>The sentiment value needs to be on the range -5 to +5.",
"group": "words",
"parameters": [
{
"name": "word",
"description": "The word whose sentiment is returned",
"dataType": "string",
"required": true,
"paramType": "path"
},
{
"name": "value",
"description": "The sentiment value of the word, must be -5 to -1 for negative or to +1 to +5 for positive connotations",
"allowableValues": {
"values": [
"-5",
"-4",
"-3",
"-2",
"-1",
"1",
"2",
"3",
"4",
"5"
],
"valueType": "LIST"
},
"dataType": "string",
"required": true,
"defaultValue": "1",
"paramType": "query"
},
{
"name": "app_id",
"description": "Your access application id",
"dataType": "string",
"paramType": "query",
"threescale_name": "app_ids"
},
{
"name": "app_key",
"description": "Your access application key",
"dataType": "string",
"paramType": "query",
"threescale_name": "app_keys"
}
]
}
]
},
{
"path": "/v1/sentence/{sentence}.json",
"operations": [
{
"httpMethod": "GET",
"summary": "Returns the aggregated sentiment of a sentence",
"description": "<p>This operation returns the aggregated value of a sentence based on the individual sentiment values of the words of the sentence.<p>The result for \"3scale rocks\" would be {\"sentence\":\"3scale rocks\",\"count\":2,\"certainty\":0.5,\"sentiment\":4.0}, overall sentiment of 4 in a -5 to +5 scale with certainty of 50% because only one word had a defined sentiment value.",
"group": "sentence",
"parameters": [
{
"name": "sentence",
"description": "The sentence to be analyzed",
"dataType": "string",
"required": true,
"paramType": "path"
},
{
"name": "app_id",
"description": "Your access application id",
"dataType": "string",
"paramType": "query",
"threescale_name": "app_ids"
},
{
"name": "app_key",
"description": "Your access application key",
"dataType": "string",
"paramType": "query",
"threescale_name": "app_keys"
}
]
}
]
}
]
}
"parameters": [
{
...
},
{
"name": "usage",
"dataType": "hash",
"required": false,
"paramType": "query",
"allowMultiple": false,
"description": "Predicted Usage. Actual usage will need to be reported with a report or an authrep.",
"parameters": [
{
"name": "metric",
"dataType": "custom",
"required": false,
"paramType": "query",
"allowMultiple": true,
"description": "Metric to be reported"
}
]
}
]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment