Module: Genius::Referents

Defined in:
lib/genius/api/referents.rb

Overview

Referents are the sections of a piece of content to which annotations are attached. Each referent is associated with a web page or a song and may have one or more annotations. Referents can be searched by the document they are attached to or by the user that created them. When a new annotation is created either a referent is created with it or that annotation is attached to an existing referent.

Constant Summary collapse

ENDPOINT =

Endpoint of the resource

"#{Api::RESOURCE}/referents".freeze

Class Method Summary collapse

Class Method Details

.referents(token: nil, options: {}) ⇒ Hash?

Referents by content item or user. Pass only one of :song_id and :web_page.

Parameters:

  • token (String?) (defaults to: nil) —

    Token to access api.genius.com.

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

    Options: :created_by_id, :text_format, :web_page_id, :song_id, :per_page, :page.

Returns:

Raises:

  • (ArgumentError) —

    if both :song_id and :web_page are present.



21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/genius/api/referents.rb', line 21

def referents(token: nil, options: {})
  return if token.nil? && !Auth.authorized?.nil?

  Errors.validate_token(token) unless token.nil?
  if options.key?(:web_page) && options.key?(:song_id)
    raise ArgumentError, 'You may pass only one of song_id and web_page_id, not both!'
  end

  params = options_helper(options, %i[created_by_id text_format per_page page])

  response = HTTParty.get("#{ENDPOINT}?access_token=#{token_ext(token)}#{params}").body
  JSON.parse(response)
end