Class: BibSonomy::API

Inherits:
Object
  • Object
show all
Defined in:
lib/bibsonomy/api.rb

Instance Method Summary collapse

Constructor Details

#initialize(user_name, api_key, format = 'ruby') ⇒ API

Initializes the client with the given credentials.

Parameters:

  • user_name (String) —

    the name of the user account used for accessing the API

  • api_key (String) —

    the API key corresponding to the user account - can be obtained from www.bibsonomy.org/settings?selTab=1

  • format (String) (defaults to: 'ruby') —

    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.



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# 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

Instance Method Details

#get_document(user_name, intra_hash, file_name) ⇒ Object

Get a document belonging to a post.

Parameters:

  • user_name
  • intra_hash
  • file_name

Returns:

  • the document and the content type



171
172
173
174
175
176
177
 
# 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) ⇒ Object 



156
157
158
159
160
161
162
 
# 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) ⇒ Object

Get the preview for a document belonging to a post.

Parameters:

  • user_name
  • intra_hash
  • file_name
  • size (String) —

    requested preview size (allowed values: SMALL, MEDIUM, LARGE)

Returns:

  • the preview image and the content type ‘image/jpeg`



187
188
189
190
191
192
193
 
# 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) ⇒ BibSonomy::Post, String

Get a single post

Parameters:

  • user_name (String) —

    the name of the post’s owner

  • intra_hash (String) —

    the intrag hash of the post

Returns:



78
79
80
81
82
83
84
85
86
87
88
89
90
 
# 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) ⇒ Array<BibSonomy::Post>, String

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

Parameters:

  • grouping (String) —

    the type of the name (either “user” or “group”)

  • name (String) —

    the name of the group or user

  • resource_type (String) —

    the type of the post. Currently supported are ‘bookmark’ and ‘publication’.

  • tags (Array<String>) (defaults to: nil) —

    the tags that all posts must contain (can be empty)

  • start (Integer) (defaults to: 0) —

    number of first post to download

  • endc (Integer) (defaults to: $MAX_POSTS_PER_REQUEST) —

    number of last post to download

Returns:



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# 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) ⇒ Array<BibSonomy::Post>, String

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

Parameters:

  • group_name (String) —

    the name of the group

  • resource_type (String) —

    the type of the post. Currently supported are ‘bookmark’ and ‘publication’.

  • tags (Array<String>) (defaults to: nil) —

    the tags that all posts must contain (can be empty)

  • start (Integer) (defaults to: 0) —

    number of first post to download

  • endc (Integer) (defaults to: $MAX_POSTS_PER_REQUEST) —

    number of last post to download

Returns:



114
115
116
 
# 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) ⇒ Array<BibSonomy::Post>, String

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

Parameters:

  • user_name (String) —

    the name of the posts’ owner

  • resource_type (String) —

    the type of the post. Currently supported are ‘bookmark’ and ‘publication’.

  • tags (Array<String>) (defaults to: nil) —

    the tags that all posts must contain (can be empty)

  • start (Integer) (defaults to: 0) —

    number of first post to download

  • endc (Integer) (defaults to: $MAX_POSTS_PER_REQUEST) —

    number of last post to download

Returns:



101
102
103
 
# 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