Module: Genius::Annotations

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

Overview

An annotation is a piece of content about a part of a document. The document may be a song (hosted on Genius) or a web page (hosted anywhere). The part of a document that an annotation is attached to is called a referent.

Class Method Summary collapse

Class Method Details

.annotations(id:, action:, token:, http_verb: "get", options: {}) ⇒ NilClass

Genius::Annotations.annotations -> true or false

GET /annotations/:id
Data for a specific annotation.

POST /annotations
Requires scope: create_annotation

Creates a new annotation on a public web page. The returned value will be the new annotation object, in the same form as would be returned by GET /annotation/:id with the new annotation's ID. Requires JSON payload. Example usage

Genius::Annotations.annotation(id:, http_verb: "post", markdown: "Foo **Bar**",
raw_annotatable_url: "https://example.com")

will reproduce JSON object via Genius::Annotations.post_payload method. According to last example it will return

{
  annotation: {
    body: {
      markdown: "Foo **Bar**"
    }
  },
  referent: {
    raw_annotatable_url: "https://example.com",
    fragment: null,
    context_for_display: {
      before_html: null,
      after_html: null
    }
  },
  web_page: {
    canonical_url: null,
    og_url: null,
    title: null
  }
}

There is a full list of possible params:

  • annotation

    * body
    * markdown - The text for the note, in
      [markdown](https://help.github.com/articles/github-flavored-markdown/) _(Required)_

  • referent

    * raw_annotatable_url - The original URL of the page _(Required)_

* fragment - The highlighted fragment _(Required)_

  • context_for_display

    * before_html - The HTML before the highlighted fragment (prefer up to 200 characters)

* after_html - The HTML after the highlighted fragment (prefer up to 200 characters)

  • web_page At least one required

    * canonical_url - The href property of the +<link rel="canonical">+ tag on the page. Including it will
  help make sure newly created annotation appear on the correct page

* og_url - The content property of the tag on the page. Including it will help make sure newly created
  annotation appear on the correct page

* title - The title of the page

PUT /annotations/:id
Requires scope: manage_annotation
Updates an annotation created by the authenticated user. Accepts the same parameters as POST /annotation above.

DELETE /annotations/:id
Requires scope: manage_annotation
Deletes an annotation created by the authenticated user.

PUT /annotations/:id/upvote
Requires scope: vote
Votes positively for the annotation on behalf of the authenticated user.

PUT /annotations/:id/downvote
Requires scope: vote
Votes negatively for the annotation on behalf of the authenticated user.

PUT /annotations/:id/unvote
Requires scope: vote
Removes the authenticated user's vote (up or down) for the annotation.

Examples:

Example usage

Genius::Annotations.annotations(id: 10225840)

Example Payload

{
  "annotation": {
    "body": {
      "markdown": "hello **world!**"
    }
  },
  "referent": {
    "raw_annotatable_url": "http://seejohncode.com/2014/01/27/vim-commands-piping/",
    "fragment": "execute commands",
    "context_for_display": {
      "before_html": "You may know that you can ",
      "after_html": " from inside of vim, with a vim command:"
    }
  },
  "web_page": {
    "canonical_url": null,
    "og_url": null,
    "title": "Secret of Mana"
  }
}

Example usage

Genius::Annotations.annotations(id: 10225840, http_verb: "put")

Example usage

Genius::Annotations.annotations(id: 10225840, http_verb: "delete")

Example usage

Genius::Annotations.annotations(id: 10225840, http_verb: "put", action: "upvote")

Example usage

Genius::Annotations.annotations(id: 10225840, http_verb: "put", action: "vote")

Example usage

Genius::Annotations.annotations(id: 10225840, http_verb: "put", action: "vote")

Parameters:

  • id (Object) —

    Identification of annotations resource.

  • action (Object) —

    Action to do during PUT request. Possible actions: nil, upvote, downvote, unvote.

  • token (String) —

    Token to access api.genius.com.

  • http_verb (String (frozen)) (defaults to: "get") —

    HTTP verb for request. Possible verbs: get, post, put, delete.

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

    Options for PUT response.

Options Hash (options:):

  • :markdown (String) —

    The text for the note, in markdown

  • :raw_annotatable_url (String) —

    The original URL of the page.

  • :fragment (String) —

    The highlighted fragment.

  • :before_html (String) —

    The HTML before the highlighted fragment (prefer up to 200 characters).

  • :after_html (String) —

    The HTML after the highlighted fragment (prefer up to 200 characters).

  • :canonical_url (String) —

    The href property of the <link rel="canonical"> tag on the page. Including it will help make sure newly created annotation appear on the correct page.

  • :og_url (String) —

    The content property of the <meta property="og:url"> tag on the page. Including it will help make sure newly created annotation appear on the correct page.

  • :title (String) —

    The title of the page.

Returns:

  • (NilClass) —

    if TokenError exceptions raised.

Raises:

  • (ArgumentError) —

    if action got incorrect value.

  • (TokenError) —

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



147
148
149
150
151
152
153
154
 
# File 'lib/genius/api/annotations.rb', line 147

def annotations(id:, action:, token:, http_verb: "get", options: {})
  return if token.nil? && !Auth.authorized?.nil?

  Errors.validate_token(token) unless token.nil?
  raise ArgumentError, "only PUT accepts `action` param" if http_verb != "put" && !action.nil?

  JSON.parse(request(id: id, action: action, token: token, http_verb: http_verb, options: options).body)
end