class BibSonomy::API

Public Class Methods

new(user_name, api_key, format = 'ruby') click to toggle source

Initializes the client with the given credentials.

@param user_name [String] the name of the user account used for accessing the API @param api_key [String] the API key corresponding to the user account - can be obtained from www.bibsonomy.org/settings?selTab=1

@param format [String] The requested return format. One of:

'xml', 'json', 'ruby', 'csl', 'bibtex'. The default is 'ruby'
which returns Ruby objects defined by this library. Currently,
'csl' and 'bibtex' are only available for publications.
# File lib/bibsonomy/api.rb, line 45
def initialize(user_name, api_key, format = 'ruby')

  # configure output format
  if format == 'ruby'
    @format = 'json'
    @parse = true
  else
    @format = format
    @parse = false
  end

  @conn = Faraday.new(:url => $API_URL) do |faraday|
    faraday.request  :url_encoded             # form-encode POST params
    #faraday.response :logger
    faraday.adapter  Faraday.default_adapter  # make requests with
                                              # Net::HTTP
  end

  @conn.basic_auth(user_name, api_key)

  # initialise URLs
  @url_post  = Addressable::Template.new("/api/users/{user_name}/posts/{intra_hash}?format={format}")
  @url_posts = Addressable::Template.new("/api/posts{?format,resourcetype,start,end,user,group,tags}")
  @url_doc   = Addressable::Template.new("/api/users/{user_name}/posts/{intra_hash}/documents/{file_name}")
end

Public Instance Methods

get_document(user_name, intra_hash, file_name) click to toggle source

Get a document belonging to a post.

@param user_name @param intra_hash @param file_name @return the document and the content type

# File lib/bibsonomy/api.rb, line 171
def get_document(user_name, intra_hash, file_name)
  response = @conn.get get_document_href(user_name, intra_hash, file_name)
  if response.status == 200
    return [response.body, response.headers['content-type']]
  end
  return nil, nil
end
get_document_href(user_name, intra_hash, file_name) click to toggle source
# File lib/bibsonomy/api.rb, line 156
def get_document_href(user_name, intra_hash, file_name)
  return @url_doc.expand({
                           :user_name => user_name,
                           :intra_hash => intra_hash,
                           :file_name => file_name
                         })
end
get_document_preview(user_name, intra_hash, file_name, size) click to toggle source

Get the preview for a document belonging to a post.

@param user_name @param intra_hash @param file_name @param size [String] requested preview size (allowed values: SMALL, MEDIUM, LARGE) @return the preview image and the content type `image/jpeg`

# File lib/bibsonomy/api.rb, line 187
def get_document_preview(user_name, intra_hash, file_name, size)
  response = @conn.get get_document_href(user_name, intra_hash, file_name), { :preview => size }
  if response.status == 200
    return [response.body, 'image/jpeg']
  end
  return nil, nil
end
get_post(user_name, intra_hash) click to toggle source

Get a single post

@param user_name [String] the name of the post's owner @param intra_hash [String] the intrag hash of the post @return [BibSonomy::Post, String] the requested post

# File lib/bibsonomy/api.rb, line 78
def get_post(user_name, intra_hash)
  response = @conn.get @url_post.expand({
                                          :user_name => user_name,
                                          :intra_hash => intra_hash,
                                          :format => @format
                                        })

  if @parse
    attributes = JSON.parse(response.body)
    return Post.new(attributes["post"])
  end
  return response.body
end
get_posts(grouping, name, resource_type, tags = nil, start = 0, endc = $MAX_POSTS_PER_REQUEST) click to toggle source

Get posts for a user or group, optionally filtered by tags.

@param grouping [String] the type of the name (either “user” or “group”) @param name [String] the name of the group or user @param resource_type [String] the type of the post. Currently supported are 'bookmark' and 'publication'. @param tags [Array<String>] the tags that all posts must contain (can be empty) @param start [Integer] number of first post to download @param endc [Integer] number of last post to download @return [Array<BibSonomy::Post>, String] the requested posts

# File lib/bibsonomy/api.rb, line 128
def get_posts(grouping, name, resource_type, tags = nil, start = 0, endc = $MAX_POSTS_PER_REQUEST)
  url = @url_posts.partial_expand({
                                    :format => @format,
                                    :resourcetype => get_resource_type(resource_type),
                                    :start => start,
                                    :end => endc
                                  })
  # decide what to get
  if grouping == "user"
    url = url.partial_expand({:user => name})
  elsif grouping == "group"
    url = url.partial_expand({:group => name})
  end
  # add tags, if requested
  if tags != nil
    url = url.partial_expand({:tags => tags.join(" ")})
  end

  response = @conn.get url.expand({})

  if @parse
    posts = JSON.parse(response.body)["posts"]["post"]
    return posts.map { |attributes| Post.new(attributes) }
  end
  return response.body
end
get_posts_for_group(group_name, resource_type, tags = nil, start = 0, endc = $MAX_POSTS_PER_REQUEST) click to toggle source

Get the posts of the users of a group, optionally filtered by tags.

@param group_name [String] the name of the group @param resource_type [String] the type of the post. Currently supported are 'bookmark' and 'publication'. @param tags [Array<String>] the tags that all posts must contain (can be empty) @param start [Integer] number of first post to download @param endc [Integer] number of last post to download @return [Array<BibSonomy::Post>, String] the requested posts

# File lib/bibsonomy/api.rb, line 114
def get_posts_for_group(group_name, resource_type, tags = nil, start = 0, endc = $MAX_POSTS_PER_REQUEST)
  return get_posts("group", group_name, resource_type, tags, start, endc)
end
get_posts_for_user(user_name, resource_type, tags = nil, start = 0, endc = $MAX_POSTS_PER_REQUEST) click to toggle source

Get posts owned by a user, optionally filtered by tags.

@param user_name [String] the name of the posts' owner @param resource_type [String] the type of the post. Currently supported are 'bookmark' and 'publication'. @param tags [Array<String>] the tags that all posts must contain (can be empty) @param start [Integer] number of first post to download @param endc [Integer] number of last post to download @return [Array<BibSonomy::Post>, String] the requested posts

# File lib/bibsonomy/api.rb, line 101
def get_posts_for_user(user_name, resource_type, tags = nil, start = 0, endc = $MAX_POSTS_PER_REQUEST)
  return get_posts("user", user_name, resource_type, tags, start, endc)
end

Private Instance Methods

get_resource_type(resource_type) click to toggle source

Convenience method to allow sloppy specification of the resource type.

# File lib/bibsonomy/api.rb, line 203
def get_resource_type(resource_type)
  if $resource_types_bookmark.include? resource_type.downcase()
    return "bookmark"
  end

  if $resource_types_bibtex.include? resource_type.downcase()
    return "bibtex"
  end

  raise ArgumentError.new("Unknown resource type:  #{resource_type}. Supported resource types are ")
end