Indiana University Indiana University
CNetS Center for Complex Networks and Systems Research
New API Specification

Givealink API Specification

Overview

The Givealink API allows you to call methods that respond in REST style xml. The API root URL is located at http://www.givealink.org/api/ Some methods are public, i.e. they do not require user authentication, others are private, e.g. write services. A user that wants to invoke a private method needs to be authenticated by way of the authentication scheme described below.

Encoding

Use UTF-8 encoding when sending arguments to API methods.

Request Styles

The user sends a request to the root URL specifying a method in the form package.method along with a set of parameters (required and/or optional ). For example, the call http://www.givealink.org/api/method?tag.getTopTags&n=10 invokes the method tag.getTopTags with the parameter n that specifies the number of most popular tags to return.

Response Styles

The API responds in XML format following the template below: <givealink status="status_message">
payload
</givealink> where:
status_message: [ ok | fail ]
payload : content of the reply
Example: <givealink status="ok">
response of the API call
</givealink> Or in case of error: <givealink status="fail">
<message>error_message</message>
<code>error_code</code>
</givealink> where error_code and error_message depend on the called API method.

Authentication

The authentication protocol allows you to perform actions on user accounts in a manner that is secure for Givealink users. All write services require authentication. TO DO: description of the adopted authentication protocol

Terms of use

Please use an identifiable User-Agent header on all requests. Like this you don't risk getting banned and it helps our logging. If you are making an application that uses Givealink data, try not to hit the API on page load. You account may be suspended if your application is continuously making more than 2 calls per second. See our terms of service for more.

Givealink API Functions

Authentication
  • Auth.getRequestToken
  • Auth.getAccessToken
Data Access'
  • Url.getSimilar : return a list of similar URLs
Params:
url (Required) : the url
n (Optional) : number of URL retrieved. The default value is 10.
Auth:
This service does not require authentication.
Sample Response:
<givealink status="ok">
<urlgetsimilar>
</urlgetsimilar>
</givealink>
Errors:
2 : Invalid parameters - Your request is missing a required parameter
3 : No method supplied - No method supplied in the request
4 : Invalid method - No method with that name in this package
6 : Invalid URL - The url specified does not exist
  • Url.getInfo
  • Url.getTags
  • Url.getRecommendedTags
Params:
url (Required) : the url
n (Optional) : number of recommended tags. The default is ?.
user (Optional): the user to recommend tags for (allows personalization)
Auth:
This service does not require authentication, unless including the user param(?).
Sample Response:
<givealink status="ok">
<urlgetrecommendedtags>
<tag method="1-1">interests</tag>
<tag method="1-2 2-1">news</tag>
<tag method="1-3">research</tag>
</urlgetrecommendedtags>
</givealink>
The 'method' attribute of tag element is for user study information -- indicates information about how recommendation was selected, so extension can phone home that information; can be removed after study is completed.
Errors:
2 : Invalid parameters - Your request is missing a required parameter
3 : No method supplied - No method supplied in the request
4 : Invalid method - No method with that name in this package
6 : Invalid URL - The url specified does not exist
  • Url.delete
  • Url.addPost (user, list of tags, url - required | title optional) [OR Post.add]
  • Url.setTitle (user , title - required)
  • Url.updatePost (user, url, list of tags - required) [OR Post.update)
  • Tag.getSimilar
  • Tag.getSimilarities
Params:
tag_list (Required) : space-separated list of tags to build similarity network for
Auth:
This service does not require authentication.
Sample Response:
<givealink status="ok">
<taggetsimilarities>
<similarity tag1="news" tag2="daily">0.1</similarity>
<similarity tag1="news" tag2="interests">0.01</similarity>
<similarity tag1="daily" tag2="interests">0.05</similarity>
</taggetsimilarities>
</givealink>
Errors:
2 : Invalid parameters - Your request is missing a required parameter
3 : No method supplied - No method supplied in the request
4 : Invalid method - No method with that name in this package
  • Tag.getTopTags
  • Tag.getInfo
  • Tag.getCentrality
  • Tag.getRecommendedTags
  • Tag.getRecommendedURLs
  • Tag.update : modifies all the triples containing the old_tag tag with the new_tag tag
Params:
user (Required) : the user name to update tags for
old_tag (Required) : the old tag
new_tag (Required) : the modified tag
Auth:
This service requires authentication. This is a write service and must be accessed with an HTTP POST request. All parameters should be sent in the POST body, including the 'method' parameter.
Sample Response:
<givealink status="ok">
</givealink>
Errors:
1 : Unauthorized user - The user does not have the right to access the service
2 : Invalid parameters - Your request is missing a required parameter
3 : No method supplied - No method supplied in the request
4 : Invalid method - No method with that name in this package
5 : Invalid user - The user does not exist
  • Tag.delete
Params:
user (Required) : the user name to update tags for
tag (Required) : the tag to delete
Auth:
This service requires authentication. This is a write service and must be accessed with an HTTP POST request. All parameters should be sent in the POST body, including the 'method' parameter.
Sample Response:
<givealink status="ok">
</givealink>
Errors:
1 : Unauthorized user - The user does not have the right to access the service
2 : Invalid parameters - Your request is missing a required parameter
3 : No method supplied - No method supplied in the request
4 : Invalid method - No method with that name in this package
5 : Invalid user - The user does not exist
  • Tag.subtag
Params:
user (Required) : the user name to update tags for
sub_tag (Required) : the 'subtag'
tag (Required) : the tag to be added to resources with subtag
Auth:
This service requires authentication. This is a write service and must be accessed with an HTTP POST request. All parameters should be sent in the POST body, including the 'method' parameter.
Sample Response:
<givealink status="ok">
</givealink>
Errors:
1 : Unauthorized user - The user does not have the right to access the service
2 : Invalid parameters - Your request is missing a required parameter
3 : No method supplied - No method supplied in the request
4 : Invalid method - No method with that name in this package
5 : Invalid user - The user does not exist
  • User.getAnnotations
Params:
user (Required) : the user name to get annotations for.
Auth:
This service requires authentication.
<givealink status="ok">
<getannotations>
<pages>
<page title='Google' url='http://www.google.com/' />
<page title='iGoogle home page' url='http://www.google.com/ig' />
</pages>
<pagetags>
<pair url='http://www.google.com/' tag='google' />
<pair url='http://www.google.com/ig' tag='google' />
</pagetags>
</getannotations>
</givealink>
  • User.getSimilar
  • User.getTags (return list if tags and centrality(optional))
  • User.getUrls (url and titles)
  • [TO DO] User.getRecommendedUsers
  • [TO DO] User.getRecommendedURLs
  • [TO DO] User.getRecommendedTags
  • User.getInfo
  • Annotation.add
  • Annotation.delete
[TO DO] * Annotation.get [TO DO] * Annotation.find Are annotations posts or triples?