HP Gloe API

8/14/2019 HP Gloe API

1/4

1

HPGloe API v1

hpgloe.com

In this document we describe the HP Gloe service API. The goal of this document is to

promote mashup services and customized clients to be written on top of Gloe and to

allow 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 the

separate An Overview of HP Gloe document.

General Protocol

All APIs support JSONP, that is a callbackHTTP 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 authentication

protocol.

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 browser

that 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 must

first register an account using the register operation (see below) to obtain a Gloenickname 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 order

using 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 1

scheme. The difference to v2 are: we don't include the parameter names in the data to

sign, we order by parameter name alphabetically, and we only support SHA1. The


2/4

2

signature must then be passed in a signature parameter. All operations apart from the

friend management operations support both authenticated and anonymous users.Anonymous users should not pass any signature parameter. Anonymous users are

identified by their IP and will have a much stricter quota for making recommendations.

ErrorsErrors 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_FOUND

Anonymous access is attempted to operation that

requires authentication

AUTHENTICATION_REQUIRED

The signature in the request was not valid AUTHENTICATION_FAILURE

The client IP could not be determined CLIENT_IDENTIFICATION_FAILED

Quota exceeded, no more recommendations

allowed

QUOTA_EXCEEDED

Location parameters missing NO_LOCATION

The channel name is not permitted INVALID_CHANNEL

The url is not permitted (must not be an IP and

must 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

OperationsParameters that need to be part of the signature apart from user name and timestamp aremarked in red.

Name Parameters Description Output Format Commentgetrec lat - latitude

(required)

lon - longitude

(required)

radius search

radius

hits - # result

items

tag channel

name

filter me,

all, friends

ref - url

reference (used

by notes

attached to web

pages)

q - string to

search for in

title or url

Return

recommendations

based on ageolocation and

various filters.

Defaults areradius: 10 miles

and hits: 10

recommendations

and no filters.

JSON array of 10-tuple with elements[,,,,,,, ,

,]

thumburl, sample and tags are all deprecated, latitude and

longitude are averages. All text is in unicode compatible

URL encoding.

If filter is not all

authentication is

required


3/4

3

rec lat latitude(required)

lon longitude

(required)

url url to

recommend

(required)

tags channel

to recommend onref url that

this

recommendation

is in reference

to

notes used

instead of url

to create notes

title title of

recommendation

click -

true/false

Recommend and

geotag web sitesor comments/notes

on web sites

JSON object with attribute message set to

RECOMMENDATION_RECORDED if all went welland attribute quote set to the remaining quota

If the url parameter

is used it is aregular

recommendation

for an existing site.If the notes

parameter is used

the url of the

recommendationwill be created

dynamically andhosted on the gloe

server. If

click=true therecommendation

does not count

towards torecommendation

quota and it is not

taken into accountwhen ranking web

sites

register nickname

requested gloe

user name

(required)email email

address of

account

(required)

Registers a new

gloe account

JSON object with message attribute set to

REGISTRATION_SUCCESS or errorattribute set toDUPLICATE_NAME_OR_EMAIL if nickname or email

already exists

(should be done over https to obtain the recommendation

key on the wire in the key attribute)

An email will be

sent to theprovided address if

registration

succeeded. The

email will contain

an activation link

and a user id. Theactivation link

must be opened in

a browser toactivate the

account. The

nickname and theuser id must be

used to sign

requests thatrequire

authentication.

friends action remove/add

(required)

friends space

separated list

of friends

Adds or removesfriends to filter onto a gloe account

JSON object with attribute message set toFRIENDS_UPDATED a nd friends set to new (spaceseparated) list of friends if all went well

Requiresauthentication

getrectag lat latitude(required)

lon longitude

(required)

radius search

radius

(required)

hits - # result

items (required)

filter -

arbitrary string

to filterchannels on

level - 1/2/...,

number of tag

hierarchies to

search

Returns mostpopular tags in a

geolocation

JSON array of 2-tuple with elements[,]

info friends -true/false,

return friends

or not

Returns current

quota and friendsof an authenticated

user

JSON object with attribute quota set to remaining quota

and attribute friends set to current friends.

Authentication

required


4/4

4

top lat - latitude(required)

lon - longitude

(required)

Get top

contributors in a

geolocation

JSON object{"top": [["", ],...],

"names": {"": {"LastName":

"", "FirstName": ""}...}}}

names attribute

provides human

readable names for

user ids if

available

Examples(URL encoding omitted for readability)

http://www.hpgloe.com/json/getrec/?lat=37.234&lon=-122.234

get all recommendations for geolocation (37.234,-122,234)

http://www.hpgloe.com/json/rec/?lat=37.234&lon=-122.234&url=http://www.hp.com&tags=hp

recommend http://www.hp.com in geolocation (37.234,-122,234) on channel hp

http://www.hpgloe.com/json/register/?nickname=tom&[email protected]

register new user with nickname tom and email [email protected]

http://www.hpgloe.com/json/friends/?action=add&friends=bob&user=tom&timestamp=200912312359&signature=sdfawefawefwefwa

Add bob as a friend to the tom account

http://www.hpgloe.com/json/getrectag/?lat=37.234&lon=-122.234Get list of most popular channels in geolocation (37.234,-122,234)

http://www.hpgloe.com/json/info/?user=tom&timestamp=20091231235959&signature=dfggergerdrg

ergerGet quota and friend info for user tom

http://www.hpgloe.com/json/top/?lat=37.234&lon=-122.234

Get top contributors in geolocation (37.234,-122,234)

HP Gloe API

Documents

Transcript of HP Gloe API