Class: Scribd::API

Inherits:
Object
  • Object
show all
Includes:
Singleton
Defined in:
lib/scribd/api.rb

Overview

This class acts as the top-level interface between Scribd and your application. Before you can begin using the Scribd API, you must specify for this object your API key and API secret. They are available on your account settings page.

This class is a singleton. Its only instance is accessed using the @instance@ class method.

To begin, first specify your API key and secret:

<pre> Scribd::API.instance.key = 'your API key here' Scribd::API.instance.secret = 'your API secret here' </pre>

(If you set the @SCRIBD_API_KEY@ and @SCRIBD_API_SECRET@ Ruby environment variables before loading the gem, these values will be set automatically for you.)

Next, you should log in to Scribd, or create a new account through the gem.

<pre>user = Scribd::User.login 'login', 'password'</pre>

You are now free to use the User or Document classes to work with Scribd documents or your user account.

If you need the User instance for the currently logged in user at a later point in time, you can retrieve it using the @user@ attribute:

<pre>user = Scribd::API.instance.user</pre>

In addition, you can save and restore sessions by simply storing this user instance and assigning it to the API at a later time. For example, to restore the session retrieved in the previous example:

<pre>Scribd::API.instance.user = user</pre>

In addition to working with Scribd users, you can also work with your own website’s user accounts. To do this, set the Scribd API user to a string containing a unique identifier for that user (perhaps a login name or a user ID):

<pre>Scribd::API.instance.user = my_user_object.mangled_user_id</pre>

A “phantom” Scribd user will be set up with that ID, so any documents you upload will be associated with that account.

For more hints on what you can do with the Scribd API, please see the Document class.

Constant Summary collapse

HOST = 
'api.scribd.com'
PORT = 
80
REQUEST_PATH = 
'/api'
TRIES = 
3

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ API

Returns a new instance of API.



81
82
83
84
85
86
87
 
# File 'lib/scribd/api.rb', line 81

def initialize
  @asychronous = false
  @key = ENV['SCRIBD_API_KEY']
  @secret = ENV['SCRIBD_API_SECRET']
  @user = User.new
  disable_multipart_post_gem
end

Instance Attribute Details

#asynchronous ⇒ true, false

Returns If true, requests are processed asynchronously. If false, requests are blocking.

Returns:

  • (true, false) —

    If true, requests are processed asynchronously. If false, requests are blocking.



76
77
78
 
# File 'lib/scribd/api.rb', line 76

def asynchronous
  @asynchronous
end

#debug=(value) ⇒ true, false

Returns If true, extended debugging information is printed.

Returns:

  • (true, false) —

    If true, extended debugging information is printed



78
79
80
 
# File 'lib/scribd/api.rb', line 78

def debug=(value)
  @debug = value
end

#key ⇒ String

Returns The API key you were given when you created a Platform account.

Returns:

  • (String) —

    The API key you were given when you created a Platform account.



70
71
72
 
# File 'lib/scribd/api.rb', line 70

def key
  @key
end

#secret ⇒ String

Returns The API secret used to validate your key (also provided with your account).

Returns:

  • (String) —

    The API secret used to validate your key (also provided with your account).



72
73
74
 
# File 'lib/scribd/api.rb', line 72

def secret
  @secret
end

#user ⇒ Scribd::User

Returns The currently logged in user.

Returns:



74
75
76
 
# File 'lib/scribd/api.rb', line 74

def user
  @user
end

Instance Method Details

#disable_multipart_post_gem ⇒ Object 



95
96
97
 
# File 'lib/scribd/api.rb', line 95

def disable_multipart_post_gem
  @use_multipart_post_gem = false
end

#enable_multipart_post_gem ⇒ Object 



89
90
91
92
93
 
# File 'lib/scribd/api.rb', line 89

def enable_multipart_post_gem
  require 'net/http/post/multipart'
  require File.expand_path('../../support/buffered_upload_io', __FILE__)
  @use_multipart_post_gem = true
end

#send_request(method, fields = {}) ⇒ Object

Raises:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/scribd/api.rb', line 100

def send_request(method, fields={})
  raise NotReadyError unless @key and @secret
  # See if method is given
  raise ArgumentError, "Method should be given" if method.nil? || method.empty?
  
  debug("** Remote method call: #{method}; fields: #{fields.inspect}")
  
  # replace pesky hashes to prevent accidents
  fields = fields.stringify_keys

  # Complete fields with the method name
  fields['method'] = method
  fields['api_key'] = @key
  
  if fields['session_key'].nil? and fields['my_user_id'].nil? then
    if @user.kind_of? Scribd::User then
      fields['session_key'] = @user.session_key
    elsif @user.kind_of? String then
      fields['my_user_id'] = @user
    end
  end
  
  fields.reject! { |k, v| v.nil? }

  # Don't include file in parameters to calculate signature
  sign_fields = fields.dup
  sign_fields.delete 'file'

  fields['api_sig'] = sign(sign_fields)
  debug("** POST parameters: #{fields.inspect}")

  res = send_request_to_scribd(fields)

  debug "** Response:"
  debug(res.body)
  debug "** End response"

  # Convert response into XML
  xml = REXML::Document.new(res.body)
  raise MalformedResponseError, "The response received from the remote host could not be interpreted" unless xml.elements['/rsp']

  # See if there was an error and raise an exception
  if xml.elements['/rsp'].attributes['stat'] == 'fail'
    # Load default code and error
    code, message = -1, "Unidentified error:\n#{res.body}"

    # Get actual error code and message
    err = xml.elements['/rsp/error']
    code, message = err.attributes['code'], err.attributes['message'] if err

    # Add more data
    message = "Method: #{method} Response: code=#{code} message=#{message}"

    raise ResponseError.new(code), message
  end

  return xml
end