1. Draugiem.lv Passport

1.1. Introduction

Draugiem.lv Passport allows external websites to introduce functions that use the profile information of draugiem.lv users.
That allows projects that are not created by draugiem.lv to access friendship links between their users and improve their
functionality based on this information.

Draugiem.lv Passport can be used in various ways. It can fully replace website registration and login system to remove
the need for every user to perform difficult registration. If the website already has a registration system, it can use
draugiem.lv Passport to link user's profile in the website with the profile in draugiem.lv.

When the user accesses a page with draugiem.lv Passport, he agrees to give his personal data to thrd party developers.

After approval process, application receives user's API key that gives it a limited access to user's data and ability to
post messages to user activity feed or profile news (if the application has permission to use these functions).

If the user wants to discontinue use of the application, he can delete if from his profile. After deletion, application
no more has access to the user's data.

1.2. Opening draugiem.lv Passport login window

To allow the user to login to a website by draugiem.lv Passport, you have to place in the site a button or a link that opens the login
window. When the user clicks on this button, a webpage or new window is opened:

it allows the user to enter his username and password, if the user is currently not logged into draugiem.lv,

it displays user's name, picture and an Allow button - if user is logged into draugiem.lv

Authorization page URL is created in this format:
http://api.draugiem.lv/authorize/?app=[app_id]&hash=[control_hash]&redirect=[redirect_url]

app:

application ID that was created when the app was created

redirect:

URL where to redirect the user after the login

hash:

32 symbol hash, MD5 function result from the application API key
and the redirect URL (e.g. if the API key is 7c437d28be62b492151788f6c827afd6 and redirect URL IS http://example.com/draugiem_auth/,
then the hash is created by calling md5('7c437d28be62b492151788f6c827afd6http://example.com/draugiem_auth/') ).

1.3. Acquiring authorization code

After the login, user will be redirected to the URL that was given in the redirect parameter, with GET variable
dr_auth_status added.

If the value of dr_auth_status is failed, user has denied the application to access his data.
If its value is ok, then the authorization has been successful and another GET parameter
dr_auth_code is added - it is authorization code that the application can use to obtain user's API key that is required
for further use of the API.

When the application has received dr_auth_code value, it an finalize the authentication process and
acquire user's API key, by performing API request authorize
(described in the section User authentication).

Some suggestions for developers

After authorization, user profile data should be kept within the session instead of requesting them repeatedly in every request.

If user data are displayed in many places in the page, they should be cached on application's side to prevent unnecessary
load both on draugiem.lv and application's servers.

If your application uses PHP, it is best to use our provided
PHP library for the integration of draugiem.lv Passport.

Passport login window has to be opened so that the address bar is visible and the user can confirm that he is entering
is pasword in a web page that belongs to draugiem.lv.

After user login, the page has to display user name that has entered the page and provide an option to log out.

To increase security, you can add IP limit to your servers in the application settings. Never perform API requests from the client side
(Javascript or Flash) - that wil make your API key exposed to everyone.

2. How to use draugiem.lv API

2.1. API requests

To acquire data or perform other actions with draugiem.lv API, application server has to perform HTTP POST or
GET requests to draugiem.lv server, providing necessary request parameters according to API specification.
Parameters can be passed as HTTP GET, POST or COOKIE variables (however, POST is recommended).

API request always must contain parameter action that contains required API action, and parameter app
that contains the API key of the application (API key is created when you create the application and it is used to identify
the application that performs API requests).

Almost always API request will contain parameter apikey, that identifies draugiem.lv user that has authorized the application.

API request was performed from address that is not within allowed addreses in application settings

105

Max API request limit in 10 minutes reached

Application has reached max request limit in 10 minutes per user.

106

Invalid or unapproved auth code

code parameter that was used in authorize request was invalid or already used.

107

Max activity limit for this user today reached

Max activity or notification count for this user per day has been reached

120

Data not found

Requested data not found

130

Spam/Flood detected

Too frequent sending of data (activities/notifications)

150

Access denied

Application does not have access to the requested data.

2.3. User data

If API request requests information related with user data, API answer will contain block users with basic profile
information of users. Every user element contains attribute uid that uniquely identifies draugiem.lv user and can be
used to create relations between user and other objects.

indicates if user has reached age 18 (1 - adult, 0 - not adult). Allows to check if user is adult even if he wants to hide his age.

img:

Profile image URL (100x100px). Empty if user has no image.

sex:

gender (M - male, F - female)

To get user profile image in different sizes, simply replace in URL part sm_ with another prefix:

i_:

50x50px icon

sm_:

100x100px icon

m_:

215px wide image

l_:

large image (max. 710x710px)

Example:
If profile image URL is http://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg, then URL of middle sized
version of this image will be http://i1.ifrype.com/profile/491/171/v3/m_491171.jpg.

2.4. Notifications about deleted users

If you fill field Delete status callback URL with your URL in application settings, draugiem.lv will notify you about users that have deleted
themself from your application or deleted their profile entirely.

That allows you to remove user information from you database or perform other actions that are necessary to perform if user
ceases to use the application.

Response to this request must contain only text OK, otherwise draugiem.lv system will try to resend status report.

3. Available API requests

3.1. User authentication process (request authorize)

Request allows application to acquire user's API key that is neccessary to perform other API requests on behalf of
the user. The request also returns user's basic profile information so that no additional requests are needed to get this data.

Request parameters:

action:

authorize

app:

application API key (32 characters)

code:

dr_auth_code value that was received as GET variable after user login (for draugiem.lv Passport applications)
or when the iframe was opened (for integrated applications)

Response will contain these parameters:

apikey:

user's API key

uid:

user ID

language:

2 letter code of the language that the user has selected in draugiem.lv

inviter:

user ID of the person who has invited this user to the application
(this element is present only when user opens application for the first time after accepting invitation)

invite_extra:

extra data that were attached to the accepted invitation by the application
(this element is present only when user opens application for the first time after accepting invitation)

User's API key allows application to access user's data via API wthout repeating authorization. After authorization application will
be added to the My Applications section of the user's profile. From there user will be able to discontinue application's
permission to access his data.

Response also contains user's profile information according to the format described in section User data.

To be able to access user's data again, application has to store the apikey value and use it in all further API requests.

If application has lost user's API key or if the user has deleted if from the profile, authorization process can be repeated.
User's API key can change if the user change his password or deletes application from the profile and joins repeatedly.

3.2. Getting user data of specific users (request userdata)

This request allows to get basic profile information of specific draugiem.lv users who have authorized the application.
This request doesn't require user's API key, just the application's key.

If request contains parameter ids, response will contain profile information of requested users according to format
described in section User data.
Only information about users that are registered in application will be returned (if the user has deleted from the application,
data will not be available anymore)

If ids parameter is not given, then API will return information about user who owns the API key passed in apikey parameter according to format
described in section User data.

3.3. Getting list of application users (request app_users)

Request allows to get a list of all users that use the application. This request doesn't require user's API key, just the application's key.

Request parameters:

action:

app_users

app:

application API key (32 characters)

show:

optional, if this parameter is given with value ids,
only list of user IDs will be returned instead of full profile data.

page:

optional, number of the page that needs to be returned. By default, first page will be returned.

limit:

optional, number of users per page (allowed range 1-200). By default one page contains 20 users.

If request does not contain parameter show with value ids, response will contain element users, filled with information
according to format described in section User data.
Element users will have an attribute total that contains total number of users.

If request contains parameter show with value ids, response will contain element userids, that will hold a list of draugiem.lv user IDs.
Element users will have an attribute total that contains total number of users.

3.5. Getting list of user's friends that use the application (request app_friends)

Request allows to get information about user's friends that use the application.

Request parameters:

action:

app_friends

app:

application API key (32 characters)

apikey:

user API key (32 characters)

show:

optional, if this parameter is given with value ids,
only list of user IDs will be returned instead of full profile data.

page:

optional, number of the page that needs to be returned. By default, first page will be returned.

limit:

optional, number of users per page (allowed range 1-200). By default one page contains 20 users.

If request does not contain parameter show with value ids, response will contain element users, filled with information
according to format described in section User data.
Element users will have an attribute total that contains total number of friends.

If request contains parameter show with value ids, response will contain element userids, that will hold a list of draugiem.lv user IDs.
Element users will have an attribute total that contains total number of friends.

Request allows to add entry with a link to user's profile activity feed (entry will be visible to all of his friends)

This feature is not enabled by default. To get permission for your application to post items to activity feed,
contact api@draugiem.lv and tell us about your application and what kind of activities it will create. Integrated applications
during the development phase are allowed to post activities in test mode (they will be visible only to the developers). To continue
posting activities after publishing, they have to be enabled by draugiem.lv staff.

Activity link must point to the same domain that is configured as application URL in application settings.

Application's icon will be shown next to the created entry. Only one activity per day can be created for each user.

Activities must comply with these principles:

Activity informs about actual user's action in the application.

Activity system can't be used for advertising.

Before starting to add new types of activities, it is highly recommended to consult with us before.

For integrated applications activity URL has to contain address that will be displayed in the iframe, not the application
address in draugiem.lv - it will automatically converted to internal address. Address opened in iframe can contain
directory path and GET variables, but might not work if it contains file name with common extensions (php/css/jpg etc.) will not work

If application will create activities that do not follow the rules, we can deny application to post new activities.

Request parameters:

action:

add_activity

app:

application API key (32 characters)

apikey:

user API key (32 characters)

prefix:

optional, text that will be displayed before the clickable link. Max length 50 characters.

text:

text of clickable activity link. Max length 100 characters.

link:

optional, URL, where the activity link will point to. If not given, link will point to application start page.
URL domain must be the same as given in the application settings. Max length 100 characters.

If activity was successfuly created, response will contain element status with value OK.

If application has no permission to post activities or if the user has blocked activities from this application,

API will respond with error 150 (Access denied).

If daily activity limit for user has been reached, API will respond with error
107 (Max activity limit for this user today reached)

Request allows to add notification with a link to user's profile news feed (it will be visible only to the user)

This feature is not enabled by default. To get permission for your application to post inotifications,
contact api@draugiem.lv and tell us about your application and what kind of notifications it will create. Integrated applications
during the development phase are allowed to post notifications in test mode (they will be visible only to the developers). To continue
posting notifications after publishing, they have to be enabled by draugiem.lv staff.

Notification link must point to the same domain that is configured as application URL in application settings.

Application's icon will be shown next to the created entry. Application can create up to 5 notifications per day for
every user, no sooner than an hour after previous one.

Notifications must comply with these principles:

Notification informs about something that has happened with user's profile in the application. It is recommended that
the notification link goes to a specific place in the application if it is possible.

Notifications can't be used to advertise application with no reason.

Before starting to add new types of notifications, it is highly recommended to consult with us before.

For integrated applications notification URL has to contain address that will be displayed in the iframe, not the application
address in draugiem.lv - it will automatically converted to internal address. Address opened in iframe can contain
directory path and GET variables, but might not work if it contains file name with common extensions (php/css/jpg etc. will not work)

If application will create notifications that do not follow the rules, we can deny application to post new notifications.

It is possible to show both notifications that come from a specific user or notifications that are displayed as created by
the application.

Important: Remember that notification is displayed to user that owns the API key that is used in request.So in order
to send notification to user that currently is not online, application has to store user's API key for offline use.

Request parameters:

prefix:

optional, text that will be displayed before the clickable link. Max length 50 characters.

text:

text of clickable activity link. Max length 100 characters.

link:

optional, URL, where the activity link will point to. If not given, link will point to application start page.
URL domain must be the same as given in the application settings. Max length 100 characters.

action:

add_notification

app:

application API key (32 characters)

apikey:

user API key (32 characters)

prefix:

optional, text that will be displayed before the clickable link. Max length 50 characters.

text:

text of clickable notification link. Max length 100 characters.

link:

optional, URL, where the notification link will point to. If not given, link will point to application start page.
URL domain must be the same as given in the application settings. Max length 100 characters.

creator:

Optional, Draugiem.lv user ID that will be displayed as sender of the notification (user ID has to belong to a registrated
user of the application; if this parameter is not given, application name will be displayed as the sender of the notification)

If notification was successfuly created, response will contain element status with value OK.

If application has no permission to post notifications or if the user has blocked notifications from this application,

API will respond with error 150 (Access denied).

If daily notification limit for user has been reached, API will respond with error
107 (Max activity limit for this user today reached)

If there is less then an hour since last added notification, request will return error 130 (Spam/Flood detected)

4. Draugiem.lv API PHP library

To make application development faster and easier, we've created a PHP library that performs API calls
and automatically converts the requested data to the PHP data structures. PHP library can be used both
for integrated applications and draugiem.lv Passport applications.