Active Docs for the Sentiment API (based on the Swagger specification)

sentiment_api.rb

#!/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]

sentiment_api_api.js

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

sentiment_api_autofill.js

"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
    ... 
  },
  ...
]

sentiment_api_base.js

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

sentiment_api_error.js

{
  "reason": "\"word\" is not a single word"
  // The error description
  "code": 422
  // HTTP Status Response Code
}

sentiment_api_operation.js

{
  // 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.
}

sentiment_api_parameter.js

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

sentiment_api_v1.json

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

service_management_api_usage_fragment.json

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