Issuu on Google+

Recommend API Versions Author

Date

Version

Description

Benoit MENET

2012/12/26

0.1

First version of the document

Gilles DASSAC

2012/01/03

0.2

Initial Revision

Gilles DASSAC

2012/02/15

0.3

Update for 1.3

Gilles DASSAC

2012/02/19

0.4

emailContact resource added

Table of contents Versions Table of contents Introduction Scope Request Responses Root Domains API Versioning Resources TOPICS Resource Description Available HTTP Methods GET Method URI Required Parameters apiKey API key — The API key is provided when the user authentication process succeed. Optional Parameters Response Fields Response Sample Return Codes PUT Method Description 1


URI Required Parameters Response Fields Response Sample Return Codes PROFILS Resource Description Available HTTP Methods POST Method URI Required Parameters Response Fields Return Codes PUT Method URI Required Parameters Response Fields Return Codes GET Method URI Required Parameters Optional Parameters Response Fields Response Sample Return Codes FRIENDS Resource Description Available HTTP Methods GET Method URI Required Parameters Response Fields Response Sample Return Codes PUT Method URI Required Parameters Optional Parameters Return Codes RECOS Resource Description Available HTTP Methods GET Method URI Required Parameters Optional Parameters 2


Response Fields Response Sample Return Codes GET Method URI Required Parameters Response Fields Return Codes POST Method URI Required Parameters Optional Parameters if there is file in the postdata (fileupload) , the filename will be used for the image file name , and the file is stored with the reco Return Codes PUT Method URI Required Parameters Optional Parameters Return Codes EMAILCONTACTS Resource Description Available HTTP Methods POST Method Description URI Required Parameters Response Fields Return Codes

Introduction Scope This document is the API documentation for Recommend.

Request Recommend API is a RESTfull API which implements this following HTTP methods : ● ● ● ●

GET will get a resource POST will create a new resource or call a service PUT will update a resource DELETE will delete a resource

3


Responses API responses are JSON formatted.

Root Domains for production : http://re.co/api/ for developement : http://support.iresa­solutions.com:8096/api/

API Versioning the version is append to the url : {domain}vx.x/ for example production v1.0 : http://re.co/api/v1.0/

4


Resources Resource

Route

Verb

Description

topics

topics/{local}/{apiKey}/

GET

Get list of topics (with flag for selection)

topics/{local}/{apiKey}/

PUT

Set my favorite topics selection

profils/{local}/{apiKey}

GET

Get my profil info

profils/{local}/

POST

Login / create account

profils/{local}/{apiKey}

PUT

Modify profil / associate fb account

friends/{apiKey}/

GET

Get my friends with status

friends/{apiKey}/

PUT

Set my friend info

reco/{local}/{id1}/{id2}/

GET

Get a reco from id ( for public / web use)

recos/{local}/{apiKey}/

GET

Get recos i can see ( my wall)

recos/{local}/{apiKey}/{UserId}/

GET

Get recos for a user (me or someone i can see)

recos/{local}/{apiKey}/

PUT

Update reco ( view / usefull / comment)

recos/{local}/{apiKey}/

POST

Post a reco

feedback

feedback/

POST

Post a feedback

friendrequests

friendrequests/{apiKey}/

GET

Get my friend requests

friendrequests/{apiKey}/

PUT

Accept / reject friend requests

notif

Notif/{apiKey}/ Notif/{apiKey}/

GET DELETE

Get my notifications Reset notifications

subscribe

Subscribe/

POST

Post a subscribe from the web

emailcontacts

emailcontacts/{apiKey}/

POST

Get email that are present in reco from a source list of email

profils

friends

reco

5


TOPICS Resource Description Provide resources for topics management

Available HTTP Methods HTTP Method

Description

GET

Provide topics list

PUT

Update user’s favorite topics

GET Method Description Provide topics list

URI topics/{local}/{apiKey}/

Required Parameters Name

Description

local

Language code — Possible value are fr or en

apiKey

API key — The API key is provided when the user authentication process succeed.

Optional Parameters Name

Description

Response Fields List of TopicResponse : Name

Type

Description

Id

int

id of the topic

Name

string

name of the topic (local)

ThemeId

int

topic theme ( 1 to 5) 6


Selected

int

selected by me (0 or 1)

Response Sample

Return Codes Code

Description

200

OK

401

Unauthorized (if apikey is wrong)

500

InternalServerError

PUT Method Description Update user’s favorite topics

URI topics/{local}/{apiKey}/

Required Parameters Name

Description

local

URL

Language code — Possible value are fr or en

apiKey

URL

API key — The API key is provided when the user authentication process succeed.

topicsUser

POSTDATA

List of favorite topic’s IDs chosen by the user

Name

Type

Description

Id

int

id of the topic

Name

string

name of the topic (local)

Response Fields List of TopicResponse :

7


ThemeId

int

topic theme ( 1 to 5)

Selected

int

selected by me (0 or 1)

Response Sample

Return Codes Code

Description

200

OK

401

Unauthorized (if apikey is wrong)

500

InternalServerError

8


PROFILS Resource Description Provide resources for user’s accounts management

Available HTTP Methods HTTP Method

Description

POST

Create a new user account or signin

GET

Get user’s account informations

PUT

Update user account

POST Method Description Create a new user account or signin 2 way of login / create account : 1) facebook (facebookUID and facebookToken are mandatory) 2) reco (email and pass are mandatory)

URI profils/{local}/

Required Parameters Name

Description

local

URL

Language code — Possible value are fr or en

facebookUID

POSTDATA

Facebook user ID — Each Facebook user are identified by a unique ID. This ID is provided by the Facebook Connect response in case of success.

facebookToken

POSTDATA

Facebook authentication token — This token is provided by the Facebook Connect response in case of success.

deviceUID

POSTDATA

Generated device UID — The generation method depends on the app editor.

email

POSTDATA

User email 9


pass

POSTDATA

User pass

firstName

POSTDATA

First name

lastName

POSTDATA

Last name

phone

POSTDATA

phone number

profileImage

POSTDATA

file name for profil image ( the image file is in the post data multipart )

TwitterUID

POSTDATA

twitter id

TwitterToken

POSTDATA

twitter token

Response Fields Name

Type

Description

apiKey

string

session id ( to be used in each call to the api)

profil

ProfilResponse

cf GET profil

Return Codes Code

Description

200

OK

500

InternalServerError

401

Unauthorized (idents are wrong)

10


PUT Method Description Update user account all field are optionnal

URI profils/{local}/{apiKey}/

Required Parameters Name

Description

local

URL

Language code — Possible value are fr or en

apiKey

URL

API key — The API key is provided when the user authentication process succeed.

facebookUID

POSTDATA

Facebook user ID — Each Facebook user are identified by a unique ID. This ID is provided by the Facebook Connect response in case of success.

facebookToken

POSTDATA

Facebook authentication token — This token is provided by the Facebook Connect response in case of success.

deviceUID

POSTDATA

Generated device UID — The generation method depends on the app editor.

email

POSTDATA

User email

pass

POSTDATA

User pass

firstName

POSTDATA

First name

lastName

POSTDATA

Last name

phone

POSTDATA

phone number

profileImage

POSTDATA

file name for profil image ( the image file is in the post data multipart )

twitterUID

POSTDATA

twitter id

twitterToken

POSTDATA

twitter token

11


Response Fields ProfilResponse : cf GET

Return Codes Code

Description

200

OK

500

InternalServerError

401

Unauthorized (if apikey is wrong)

GET Method Description Get the authentified user’s account informations

URI profils/{local}/{apiKey}/

Required Parameters Name

Description

local

URL

Language code — Possible value are fr or en

apiKey

URL

API key — The API key is provided when the user authentication process succeed.

Optional Parameters Name

Description

Response Fields ProfilResponse :

12


Name

Type

Description

id

int

not used

name

string

Name

hash

string

hash ( id) of the user

surName

string

Surname

email

string

Email

url

string

url to the user home (not used yet)

pooling

int

time to pool (not used)

nbReco

int

nb reco posted

nbRelevance

int

nb relevance received on reco posted

nbActiveTopics

int

nb topics selected

topics

List<TopicResponse>

cf GET topics

friends

List<RecoFriend>

cf GET friends

friendRequests

List<FriendRequestResponse>

cf GET friendRequests

notifs

int

nb notification pending

Response Sample

Return Codes Code

Description

200

OK

401

Unauthorized (if apikey is wrong)

500

InternalServerError

13


FRIENDS Resource Description Provide resources for user’s friends management

Available HTTP Methods HTTP Method

Description

GET

Get user’s friends

PUT

Update user’s friends

GET Method Description Get user’s friends

URI friends/{apiKey}/

Required Parameters Name

Description

apiKey

API key — The API key is provided when the user authentication process succeed.

Response Fields FriendResponse : Name

Type

Description

potentialFriends

list<PotentialFriend>

List of potential friends for an authentified user.

recommendFriends

list<RecoFriend>

List of Recommend friends for an authentified user.

friendRequests

List<FriendRequestResponse>

list of pending requests cf GET friendRequest

14


RecoFriend : Name

Type

Description

Id

string

Hash of the friend

Name

string

Name of hte friend

fbId

string

facebookid

Request

int

0 not in request , 1 in request

util_town

string

town of the friend

util_topic

List<int>

List of topic id

nbRecos

int

nb recos posted

nbRelevants

int

ne relevants received

Name

Type

Description

Source

string

source of friend ( CONT / FB …)

Id

string

Hash of the friend

Name

string

Name of hte friend

fbId

string

facebookid

email

string

Email

PotentialFriend :

Response Sample

Return Codes Code

Description

200

OK

401

Unauthorized (if apikey is wrong)

500

InternalServerError

15


PUT Method Description Get user’s friends

URI friends/{apiKey}/

Required Parameters Name

Description

apiKey

API key — The API key is provided when the user authentication process succeed.

Optional Parameters Name

Description

AddToFriends

POSTDATA

list of  friend to add (Potentialfriend)

RemoveFromFriends

POSTDATA

list of friend to remove (recofriend)

accepts

POSTDATA

list of friend to accept ( friend request)

rejects

POSTDATA

list of friend to reject( friend request)

Return Codes Code

Description

200

OK

401

Unauthorized (if apikey is wrong)

500

InternalServerError

16


RECOS Resource Description Provide resources for reco feed management

Available HTTP Methods HTTP Method

Description

GET

Get the reco feed

POST

Post a new reco

PUT

Update reco fields

GET Method Description Get the reco feed

URI recos/{local}/{apiKey}/?parameters recos/{local}/{apiKey}/{userId}/?parameters

Required Parameters Name

Description

local

Language code — Possible value are fr or en

apiKey

API key — The API key is provided when the user authentication process succeed.

Optional Parameters Name

Description

userId

user hash to filter recos

lastId

Reco’s ID which is on the top of the feed — If provided, the response begins from this specific reco’s ID. Begins from the top of the feed otherwise. To use with qty parameter for pagination.

qty

Number of recos desired in the feed 17


response — If not provided, all values are return To use with lastId parameter for pagination. topicIds

list of Topic ID — If provided, the reco feed is filtered on the given topic.

Lat

Lat of the recos

Long

Long of the recos

Response Fields List of RecoResponse : Name

Type

Description

Hash

string

reco id

URL

string

reco url (for web view)

DatePublish

string

reco date

TimeStamp

long

reco date in timestamp format

UserId

string

user hash of the reco author

ViaUserId

string

user hash of the reco fowarder

User

string

user name of the reco author

ViaUser

string

user name of the reco fowarder

UserfbId

string

user fb id of the reco author

ViaUserfbId

string

user fb id of the reco fowarder

Title

string

reco title

Text

string

reco text

Image Location

string string

reco image link reco location ( gmap format)

Topics

List<int>

list of topics id for the reco

TopicsName

List<string>

list of topics name for the reco

Rate

int

rate of the reco 18


Lat

string

latitude

Long

string

longitude

Views

int

nb views for the reco

Usefull

int

nb usefull for the reco

Comments

int

nb comment for the reco

fb

int

1 if shared on FB else 0

tw

int

1 if shared on TW else 0

UserUsefull

int

1 if i’v already tagged usefull else 0

Response Sample

Return Codes Code

Description

200

OK

401

Unauthorized (if apikey is wrong)

500

InternalServerError

GET Method Description Get the reco for the web

URI recos/{local}/{id1}/{id2}/

Required Parameters Name

Description

id1

first 4 carac. of the reco hash

id2

last 4 carac. of the reco hash

Response Fields List of RecoResponse :  cf GET recos 19


Return Codes Code

Description

200

OK

401

Unauthorized (if apikey is wrong)

500

InternalServerError

POST Method Description Post a new reco

URI recos/{local}/{apiKey}/

Required Parameters Name

Description

local

URL

Language code — Possible value are fr or en

apiKey

URL

API key — The API key is provided when the user authentication process succeed.

Optional Parameters Name

Description

Title

POSTDATA

Title of the reco

Text

POSTDATA

Text content of the reco

Location

POSTDATA

Location (as returned by gmap)

Rate

POSTDATA

Rate of the reco (0 ­ 5)

Topics

POSTDATA

List of topics id for the reco

Lat

POSTDATA

latitude

Long

POSTDATA

longitude

fb

POSTDATA

1 if post on FB , 0 otherwise 20


tw

POSTDATA

1 if post on TW , 0 otherwise

if there is file in the postdata (fileupload) , the filename will be used for the image file name , and the file is stored with the reco Return Codes Code

Description

200

OK

401

Unauthorized (if apikey is wrong)

500

InternalServerError

PUT Method Description Update reco fields for a given reco ID

URI recos/{local}/{apiKey}

Required Parameters Name local apiKey

Description URL URL

Language code — Possible value are fr or en API key — The API key is provided when the user authentication process succeed.

Optional Parameters Name

Description

hash

Reco’s ID

addView

Add +1 to the number of views — If set to 1, put +1 to the counter. If set to 0, no change.

addUsefull

Add +1/­1 to the relevant counter — If set to 1, put +1 to the counter. If set to ­1, put ­1 to the counter. If set to 0, no��change.

Return Codes Code

Description

21


200

OK

401

Unauthorized (if apikey is wrong)

500

InternalServerError

EMAILCONTACTS Resource Description Provide resources for finding email in recommend

Available HTTP Methods HTTP Method

Description

POST

Update user’s favorite topics

POST Method Description Send email list and get inx of the one that are in recommend

URI emailcontacts/{apiKey}/

Required Parameters Name

Description

apiKey

URL

API key — The API key is provided when the user authentication process succeed.

emails

POSTDATA

List of of email

Response Fields List of int : index (in the list sent) of the email that are presentResponse Sample

Return Codes Code

Description 22


200

OK

401

Unauthorized (if apikey is wrong)

500

InternalServerError

23


API RECO