• Embed Doc
  • Copy Link
  • Readcast
  • Collections
  • CommentGo Back
Download
 
1
HP 
Gloe API v1
hpgloe.comIn this document we describe the
HP
Gloe service API. The goal of this document is topromote mashup services and customized clients to be written on top of Gloe and toallow syndication of Gloe content. The API also allows native clients to be built forplatforms that Gloe currently does not support. For a general description of Gloe see theseparate
An Overview of HP Gloe
document.
General Protocol 
All APIs support JSONP, that is a
callback 
HTTP GET parameter may be passed and theresult is then the string
 callback
(
  json data
);All operations may be called using HTTP GET with the format:
http://
www.hpgloe.com 
/json/
operation
/?
 param1
=
val1
&
 param2
=
val2
…
Authentication 
Most operations can be called without requiring authentication. There are two ways of authenticating a user, with Facebook Connect, and with the native Gloe authenticationprotocol.To initiate a Facebook Connect login a browser should be opened with the URL:http:// 
www.hpgloe.com
 /json/ 
mobilefblogin
 / This will direct the user to the Facebook login page and set the cookies in the browserthat are required to link the users’ Facebook account with a corresponding Gloe account.For first time logins a new Gloe account will be created dynamically/ For more information about Facebook connect see
http://developers.facebook.com/connect.php
To login to a native Gloe account (without requiring a Facebook identity) the user mustfirst register an account using the register operation (see below) to obtain a Gloe
nickname
and
recommendation key
. Authenticated requests must contain a
timestamp
parameter with the current time using the time format
%Y%m%d%H%M%S,
e.g. 20091231235959. The request must also contain a
user 
parameter with the
nickname
of a registered Gloe user. The parameter values must then be signed in alphabetical orderusing the HMAC/SHA1 algorithm (See e.g., the Authentication section in
http://docs.amazonwebservices.com/AWSEC2/latest/DeveloperGuide/index.html?using-query-api.html
for implementationdetails) with the
recommendation key
. Note Gloe uses the AWS signature version 1scheme. The difference to v2 are: we don't include the parameter names in the data tosign, we order by parameter name alphabetically, and we only support SHA1. The
 
2signature must then be passed in a
signature
parameter. All operations apart from thefriend management operations support both authenticated and anonymous users.Anonymous users should not pass any signature parameter. Anonymous users areidentified by their IP and will have a much stricter quota for making recommendations.
Errors 
Errors are returned inside a JSON object with attribute
error 
. Eg.
{“error”: “
error string 
”}
Error Error String
User that tries to authenticate is not found USER_NOT_FOUNDAnonymous access is attempted to operation thatrequires authenticationAUTHENTICATION_REQUIREDThe signature in the request was not valid AUTHENTICATION_FAILURE
 
The client IP could not be determined CLIENT_IDENTIFICATION_FAILED
 
Quota exceeded, no more recommendationsallowedQUOTA_EXCEEDEDLocation parameters missing NO_LOCATIONThe channel name is not permitted INVALID_CHANNEL
 
The url is not permitted (must not be an IP andmust not be blacklisted)INVALID_URL
 
The note text is not permitted INVALID_NOTE
 
The nickname is not permitted INVALID_NICKNAME
 
The email is not permitted INVALID_EMAIL
 
The nickname or email already exists DUPLICATE_NAME_OR_EMAIL
 
The recommendation was not successful RECOMMENDATION_FAILED
Operations 
Parameters that need to be part of the signature apart from user name and timestamp aremarked in red.
 
Name Parameters Description Output Format Comment
getrec
lat- latitude(
required
)lon- longitude(
required
)radius – searchradiushits - # resultitemstag– channelnamefilter– me,all, friendsref - urlreference (usedby notesattached to webpages)q - string tosearch for intitle or url
Returnrecommendationsbased on ageolocation andvarious filters.Defaults areradius: 10 milesand hits: 10recommendationsand no filters.JSON array of 10-tuple with elements
[<rank>,<url>,<title>,<thumburl>,<sample>,<tags>,<latitude>, <longitude>,<clicks>,<distance>]
thumburl, sample and tags are all deprecated, latitude andlongitude are averages. All text is in unicode compatibleURL encoding.If filter is not
all
authentication isrequired
 
3
rec
lat– latitude(
required
)lon– longitude(
required
)url– url torecommend(
required
)tags– channelto recommend onref – url thatthisrecommendationis in referencetonotes – usedinstead of urlto create notestitle – title ofrecommendationclick -true/false
Recommend andgeotag web sitesor comments/noteson web sitesJSON object with attribute
message
set toRECOMMENDATION_RECORDED if all went welland attribute
quote
set to the remaining quotaIf the url parameteris used it is aregularrecommendationfor an existing site.If the notesparameter is usedthe url of therecommendationwill be createddynamically andhosted on the gloeserver. If click=true therecommendationdoes not counttowards torecommendationquota and it is nottaken into accountwhen ranking websites
 
register
nickname –requested gloeuser name(
required
)email – emailaddress ofaccount(
required
)
Registers a newgloe accountJSON object with
message
attribute set toREGISTRATION_SUCCESS or
error 
attribute set toDUPLICATE_NAME_OR_EMAIL if nickname or emailalready exists(should be done over https to obtain the recommendationkey on the wire in the
key
attribute)An email will besent to theprovided address if registrationsucceeded. Theemail will containan activation link and a user id. Theactivation link must be opened ina browser toactivate theaccount. Thenickname and theuser id must beused to signrequests thatrequireauthentication.
 
friends
action–remove/add(
required
)friends– spaceseparated listof friends
Adds or removesfriends to filter onto a gloe accountJSON object with attribute
message
set toFRIENDS_UPDATED and
friends
set to new (spaceseparated) list of friends if all went wellRequiresauthentication
 
getrectag
lat – latitude(
required
)lon – longitude(
required
)radius – searchradius(
required
)hits - # resultitems (
required
)filter -arbitrary stringto filterchannels onlevel - 1/2/...,number of taghierarchies tosearch
Returns mostpopular tags in ageolocationJSON array of 2-tuple with elements
[<rank>,<tag>]
 
info
friends -true/false,return friendsor not
Returns currentquota and friendsof an authenticateduserJSON object with attribute
quota
set to remaining quotaand attribute
friends
set to current friends.Authenticationrequired
of 00

Leave a Comment

You must be to leave a comment.
Submit
Characters: ...
You must be to leave a comment.
Submit
Characters: ...