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"

Class Method Summary collapse

Class Method Details

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

Genius::Referents.referents -> Hash

Referents by content item or user responsible for an included annotation. You may pass only one of song_id and web_page_id, not both.

Parameters:

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

Options Hash (options:):

  • :created_by_id (Integer) —

    ID of a user to get referents for.

  • :text_format (String) —

    Format for text bodies related to the document. One or more of dom, plain, and html, separated by commas (defaults to dom). See details of each option here.

  • :web_page_id (Integer) —

    ID of a web page to get referents for.

  • :song_id (Integer) —

    ID of a song to get referents for.

  • :per_page (Integer) —

    Number of results to return per request.

  • :page (Integer) —

    Paginated offset, (e.g., per_page=5&page=3 returns songs 11-15).

Returns:

Raises:

  • (ArgumentError) —

    if song_id and web_page are presented in the same scope.

  • (TokenError) —

    if token or Genius::Auth.token are invalid.



37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/genius/api/referents.rb', line 37

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