Class: RARBG::API

Inherits:
Object
  • Object
show all
Defined in:
lib/rarbg/api.rb

Overview

Base class for RARBG API.

Constant Summary collapse

API_ENDPOINT =

RARBG API endpoint.

'https://torrentapi.org/pubapi_v2.php'
APP_ID =

App name identifier.

'rarbg-rubygem'
TOKEN_EXPIRATION =

Default token expiration time (seconds).

800
RATE_LIMIT =

Default API rate limit (seconds).

2.1

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ API

Initialize a new instance of RARBG::API.

Examples:

rarbg = RARBG::API.new


56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/rarbg/api.rb', line 56

def initialize
  @connection = Faraday.new(url: API_ENDPOINT) do |conn|
    conn.response :logger if $VERBOSE
    conn.adapter  Faraday.default_adapter

    conn.options.timeout      = 30
    conn.options.open_timeout = 10

    conn.headers[:user_agent] = APP_ID
    conn.params[:app_id]      = APP_ID
  end
end

Instance Attribute Details

#connection ⇒ Faraday::Connection (readonly)

Note:

For more info regarding this object refer to the Faraday documentation.

The underlying Faraday::Connection object used to perform requests.

Returns:

  • (Faraday::Connection) —

    The Faraday connection object.



31
32
33
 
# File 'lib/rarbg/api.rb', line 31

def connection
  @connection
end

#last_request ⇒ Float (readonly)

The monotonic timestamp of the last request performed. Used to comply with the endpoint rate limit based on RATE_LIMIT.

Returns:

  • (Float) —

    The monotonic timestamp of the last request performed.



37
38
39
 
# File 'lib/rarbg/api.rb', line 37

def last_request
  @last_request
end

#token ⇒ String (readonly)

The token used for authentication. This is generated and rate limited automatically when calling #list or #search, but can also be generated forcefully using #token!.

Returns:

  • (String) —

    The token used for authentication.



44
45
46
 
# File 'lib/rarbg/api.rb', line 44

def token
  @token
end

#token_time ⇒ Float (readonly)

The monotonic timestamp of the token request. Used to compute the next required token request based on TOKEN_EXPIRATION.

Returns:

  • (Float) —

    The monotonic timestamp of the token request.



50
51
52
 
# File 'lib/rarbg/api.rb', line 50

def token_time
  @token_time
end

Instance Method Details

#list(params = {}) ⇒ Array<Hash>

List torrents.

Examples:

List last 100 ranked torrents in Movies/x264/1080 category

rarbg = RARBG::API.new
rarbg.list(limit: 100, ranked: true, category: [44])

List torrents with at least 50 seeders

rarbg = RARBG::API.new
rarbg.list(min_seeders: 50)

Parameters:

  • params (Hash) (defaults to: {}) —

    A customizable set of parameters.

Options Hash (params):

  • :category (Array<Integer>) —

    Filter results by category.

  • :format (Symbol) —

    Format results. Accepted values: :json, :json_extended. Default: :json.

  • :limit (Integer) —

    Limit results number. Accepted values: 25, 50, 100. Default: 25.

  • :min_seeders (Integer) —

    Filter results by minimum seeders.

  • :min_leechers (Integer) —

    Filter results by minimum leechers.

  • :ranked (Boolean) —

    Include/exclude unranked torrents. Default: true.

  • :sort (Symbol) —

    Sort results. Accepted values: :last, :seeders, :leechers. Default: :last.

Returns:

  • (Array<Hash>) —

    Torrents that match the specified parameters.

Raises:

  • (ArgumentError) —

    If params is not an Hash.

  • (RARBG::APIError) —

    If the request fails or the endpoint responds with an error.

  • (Faraday::Error) —

    On low-level connection errors (e.g. timeouts).



102
103
104
105
106
107
 
# File 'lib/rarbg/api.rb', line 102

def list(params = {})
  raise ArgumentError, 'Expected params hash' unless params.is_a?(Hash)

  params.update(mode: 'list', token: token?)
  call(params)
end

#search(params = {}) ⇒ Array<Hash>

Search torrents.

Examples:

Search by IMDb ID, sorted by leechers and in extended format.

rarbg = RARBG::API.new
rarbg.search(imdb: 'tt2488496', sort: :leechers, format: :json_extended)

Search unranked torrents by string, with at least 2 seeders.

rarbg = RARBG::API.new
rarbg.search(string: 'Star Wars', ranked: false, min_seeders: 2)

Parameters:

  • params (Hash) (defaults to: {}) —

    A customizable set of parameters.

Options Hash (params):

  • :string (String) —

    Search by string.

  • :imdb (String) —

    Search by IMDb id.

  • :tvdb (String) —

    Search by TVDB id.

  • :themoviedb (String) —

    Search by The Movie DB id.

  • :category (Array<Integer>) —

    Filter results by category.

  • :format (Symbol) —

    Format results. Accepted values: :json, :json_extended. Default: :json.

  • :limit (Integer) —

    Limit results number. Accepted values: 25, 50, 100. Default: 25.

  • :min_seeders (Integer) —

    Filter results by minimum seeders.

  • :min_leechers (Integer) —

    Filter results by minimum leechers.

  • :ranked (Boolean) —

    Include/exclude unranked torrents. Default: true.

  • :sort (Symbol) —

    Sort results. Accepted values: :last, :seeders, :leechers. Default: :last.

Returns:

  • (Array<Hash>) —

    Torrents that match the specified parameters.

Raises:

  • (ArgumentError) —

    If params is not an Hash.

  • (ArgumentError) —

    If no search type param is passed (among string, imdb, tvdb, themoviedb).

  • (RARBG::APIError) —

    If the request fails or the endpoint responds with an error.

  • (Faraday::Error) —

    On low-level connection errors (e.g. timeouts).



148
149
150
151
152
153
 
# File 'lib/rarbg/api.rb', line 148

def search(params = {})
  raise ArgumentError, 'Expected params hash' unless params.is_a?(Hash)

  params.update(mode: 'search', token: token?)
  call(params)
end

#token! ⇒ String

Generate the authentication token.

Examples:

Generate the token immediately after object instantiation.

rarbg = RARBG::API.new
rarbg.token!

Returns:

  • (String) —

    The currently valid authentication token.



162
163
164
 
# File 'lib/rarbg/api.rb', line 162

def token!
  token?
end