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

#initializeAPI

Initialize a new instance of RARBG::API.

Examples:

rarbg = RARBG::API.new


52
53
54
55
56
57
58
59
60
61
62
63
64
65
# File 'lib/rarbg/api.rb', line 52

def initialize
  @conn = Faraday.new(url: API_ENDPOINT) do |conn|
    conn.request  :json
    conn.response :json, content_type: /\bjson$/
    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

#connFaraday::Connection (readonly)

Returns the Faraday connection object.

Returns:

  • (Faraday::Connection)

    the Faraday connection object.



26
27
28
# File 'lib/rarbg/api.rb', line 26

def conn
  @conn
end

#last_requestInteger (readonly)

Returns the monotonic timestamp of the last request performed.

Returns:

  • (Integer)

    the monotonic timestamp of the last request performed.



35
36
37
# File 'lib/rarbg/api.rb', line 35

def last_request
  @last_request
end

#tokenString (readonly)

Returns the token used for authentication.

Returns:

  • (String)

    the token used for authentication.



29
30
31
# File 'lib/rarbg/api.rb', line 29

def token
  @token
end

#token_timeInteger (readonly)

Returns the monotonic timestamp of the token request.

Returns:

  • (Integer)

    the monotonic timestamp of the token request.



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

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

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>)

    Return torrents that match the specified parameters.

Raises:

  • (ArgumentError)

    Exception raised if params is not an Hash.

  • (RARBG::APIError)

    Exception raised when the request fails or the endpoint responds with an error.

  • (Faraday::Error)

    Exception raised on low-level connection errors (e.g. timeouts).



98
99
100
101
102
103
104
105
106
# File 'lib/rarbg/api.rb', line 98

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>)

    Return torrents that match the specified parameters.

Raises:

  • (ArgumentError)

    Exception raised if params is not an Hash.

  • (ArgumentError)

    Exception raised if no search type param is passed (among string, imdb, tvdb, themoviedb).

  • (RARBG::APIError)

    Exception raised when the request fails or the endpoint responds with an error.

  • (Faraday::Error)

    Exception raised on low-level connection errors (e.g. timeouts).



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

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)

    Return the currently valid token.



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

def token!
  token?
end