Aplikācijas

Draugiem.lv Pases API dokumentācija

1.   Draugiem.lv pase

1.1.   Ievads

Draugiem.lv pase sniedz iespēju ar draugiem.lv nesaistītās tīmekļa lapās ieviest funkcijas, kas izmanto draugiem.lv lietotāju informāciju. Tādā veidā dažādi draugiem.lv neizstrādāti projekti var piekļūt savu lietotāju savstarpējām draudzības saitēm un piedāvāt uz tām balstītu funkcionalitāti.

Draugiem.lv pasi var izmantot dažādi. Tā var pilnībā aizstāt mājas lapas reģistrācijas un pieteikšanās sistēmu, ļaujot katram draugiem.lv lietotājam sākt izmantot lapas iespējas, neveicot nekādu reģistrāciju. Ja lapai jau eksistē reģistrācijas sistēma, tad draugiem.lv pase var tikt izmantota lai piesaistītu lietotāja draugiem.lv profilu jau eksistējošam ārējās lapas lietotāja kontam.

Pirmo reizi ienākot lapā ar draugiem.lv pasi, lietotājs piekrīt nodot savu profila informāciju trešās puses izstrādātājiem.

Pēc piekļuves apstiprināšanas aplikācija iegūst lietotāja API atslēgu, kas dod tai piekļuvi ierobežotam apjomam lietotāja datu (profila pamatinformācija, un informācija par lietotāja draugiem, kas izmanto šo pašu aplikāciju), kā arī iespēju pievienot aktivitātes un profila jaunumus lietotāja profilā (ja šīs iespējas aplikācijai ir pieejamas un lietotājs nav aizliedzis pievienošanu).

Ja lietotājs pēc kāda laika vēlas pārtraukt lapas piekļuvi saviem datiem, viņš var atteikties no tās, izmantojot funkciju savā draugiem.lv profilā. Kopš atteikšanās brīža lietotāja dati attiecīgajai aplikācijai vairs nav pieejami.

1.2.   Draugiem.lv pases pieteikšanās loga atvēršana

Lai lietotājs varētu pieteikties lapā, izmantojot draugiem.lv pasi, tajā jāievieto poga vai saite, kas atver draugiem.lv pases pieteikšanās lapu. Noklikšķinot uz šīs saites, tiks atvērta lapa vai logs, kurā:

  1. lietotājam piedāvā ievadīt draugiem.lv reģistrācijas datus, ja lietotājs tobrīd nav ienācis draugiem.lv,
  2. redzams lietotāja vārds, uzvārds, attēls un poga Atļaut - ja lietotājs tobrīd ir ienācis draugiem.lv
img/pase1.png

Autorizācijas lapas saites adrese veidojas šādā formā: http://api.draugiem.lv/authorize/?app=[aplikācijas_id]&hash=[kontroles_kods]&redirect=[pāradresācijas_adrese]

app:aplikācijas id, kas redzams draugiem.lv izveidotās aplikācijas uzstādījumos
redirect:adrese, uz kuru jāpārsūta lietotājs pēc pieteikšanās
hash:32 simbolu kods, MD5 funkcijas rezultāts no aplikācijas API atslēgas un pāradresācijas adreses apvienojuma (piemēram, ja aplikācijas API atslēga ir 7c437d28be62b492151788f6c827afd6 un adrese, uz kuru jāveic pāradresācija, ir http://example.com/draugiem_auth/, tad kontroles kods ir iegūstams, izsaucot md5('7c437d28be62b492151788f6c827afd6http://example.com/draugiem_auth/') ).

1.3.   Autorizācijas koda iegūšana

Pēc pieteikšanās lietotājs tiks pāradresēts uz lapu, kuras adrese tika norādīta parametrā redirect, pievienojot tai galā GET parametru dr_auth_status. Ja dr_auth_status vērtība ir failed, lietotājs nav ļāvis aplikācijai piekļūt viņa datiem. Ja šī parametra vērtība ir ok, tad pieteikšanās ir bijusi veiksmīga, un adresei ir pievienots arī GET parametrs dr_auth_code - autorizācijas kods, ar kura palīdzību aplikācija var iegūt lietotāja API atslēgu, kas ir nepieciešama turpmākai API izmantošanai.

Kad aplikācija ir saņēmusi dr_auth_code vērtību, tā var pabeigt pieteikšanās procesu un iegūt lietotāja API atslēgu, 20 minūšu laikā veicot API pieprasījumu authorize (sīkāks šī pieprasījuma apraksts atrodams nodaļā Lietotāja autorizācija).

Daži ieteikumi izstrādātājiem

Lai maksimāli pareizi un efektīgi izmantotu draugiem.lv pases iespējas, vēlams sekot šādiem principiem:

  • Pēc lietotāja autorizācijas iegūto informāciju par lietotāju vēlams glabāt sesijā, nevis pie katras lapas atvēršanas prasīt atkārtoti caur draugiem.lv API.
  • Ja lapā daudzās vietās jāattēlo lietotāju dati, tad arī tos vēlams uzglabāt lokāli un atjaunot ik pēc laika, nevis pie katra pieprasījuma, lai lieki nenoslogotu gan savu, gan draugiem.lv serveri.
  • Ja jūsu lapa izstrādāta PHP valodā, visērtāk draugiem.lv pasi ieviest, izmantojot mūsu sagatavoto PHP koda bibliotēku.
  • Pases pieteikšanās logs jāatver tā, lai būtu redzams adreses lauks, un lietotājs varētu pārliecināties, ka ievada savu paroli lapā, kas atrodas zem draugiem.lv domēna.
  • Pēc lietotāja pieteikšanās lapā jābūt redzamai informācijai par to, kurš lietotājs ir ienācis lapā, kā arī iespējai iziet no lapas (pārtraukt lietotāja sesiju).
  • Ja vēlaties, lai jūsu lapa būtu redzama visiem draugiem.lv apmeklētājiem sadaļā Aplikācijas, vai arī vēlaties iegūt savai lapai tiesības pievienot informāciju draugiem.lv lietotāju profila aktivitātēs, rakstiet e-pastu uz api@draugiem.lv
  • Lai parādītu lietotājiem, ka lapā iespējams pieteikties ar draugiem.lv pasi, vēlams lietot kādu no mūsu piedāvātajiem draugiem.lv pases logo
  • Nodrošiniet, lai neviens cits neuzzinātu Jūsu lapas API atslēgu. Lai palielinātu drošību, ierobežojiet jūsu aplikācijas piekļuvi draugiem.lv API tikai no jūsu servera IP adreses (to var izdarīt aplikācijas uzstādījumos). Nekādā gadījumā neveiciet API pieprasījumus no klienta puses (Javascript vai Flash vidēs) - tā jūsu API atslēga kļūs pieejama visiem.

2.   API lietošana

2.1.   API pieprasījumu veikšana

Lai iegūtu datus vai veiktu citas darbības ar draugiem.lv API, aplikācijas serveris veic HTTP POST vai GET pieprasījumu uz draugiem.lv serveri, norādot parametros vērtības atbilstoši attiecīgā pieprasījuma specifikācijai. Parametri var tikt padoti, izmantojot HTTP GET, POST un COOKIE mainīgos.

Adrese, uz kuru jāsūta draugiem.lv API pieprasījumi, ir atkarīga no izvēlētā datu apmaiņas formāta. Pieejami šādi datu apmaiņas formāti:

Formāts Paskaidrojums API adrese
XML atbildes uz API pieprasījumiem tiek pārsūtītas XML formātā http://api.draugiem.lv/xml/
PHP atbildes uz API pieprasījumiem tiek pārsūtītas PHP serializēto datu formātā http://api.draugiem.lv/php/
JSON atbildes uz API pieprasījumiem tiek pārsūtītas JSON datu formātā http://api.draugiem.lv/json/
PLIST atbildes uz API pieprasījumiem tiek pārsūtītas Apple Property List XML datu formātā http://api.draugiem.lv/cocoa/

Dokumentācijā aprakstītajos piemēros parādīts, kādas izskatās draugiem.lv API pieprasījumu atbildes, izmantojot XML datu apmaiņas formātu. Draugiem.lv API PHP bibliotēka izmanto PHP serializēto datu apmaiņas formātu.

API pieprasījumam vienmēr jāsatur parametrs action, kas norāda izsaucamo darbību, un parametrs app, kas satur izveidotās aplikācijas API atslēgu (API atslēga tiek piešķirta, izveidojot aplikāciju, un tā tiek izmantota, lai identificētu aplikāciju, kas veic pieprasījumus).

API pieprasījumam gandrīz vienmēr jāsatur arī parametrs apikey, kas identificē draugiem.lv lietotāju,
kura vārdā aplikācija veic pieprasījumus.

Piemērs: Lai iegūtu lietotāja profila pamatinformāciju XML formātā (aplikācijas API atslēga - 52967e99b3c11a755e7635901c23c0cf, lietotāja API atslēga - 208d970441dd5f3e87b965fedabd0738), jāveic šāds API pieprasījums:

http://api.draugiem.lv/xml/?app=52967e99b3c11a755e7635901c23c0cf&apikey=208d970441dd5f3e87b965fedabd0738&action=userdata

Atbilstoši veiktajam pieprasījumam, serveris atbild ar datu struktūru izvēlētajā formātā, kas satur atbildes datus:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users>
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <nick>Janka</nick>
                        <place>Rīga</place>
                        <age/>
                        <adult>1</adult>
                        <img>http://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <sex>M</sex>
                </user>
        </users>
</draugiem>

2.2.   Kļūdu statusa kodi

Ja aplikācija veikusi nekorektu API pieprasījumu vai arī notikusi cita kļūda, atbilde uz API pieprasījumu satur kļūdas kodu un aprakstu.

Paraugs XML formātā:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <error code="150">Access denied</error>
</draugiem>

Paraugs PHP formātā:

a:1:{s:5:"error";a:2:{s:11:"description";s:13:"Access denied";s:4:"code";i:150;}}

Paraugs JSON formātā:

{"error":{"description":"Access denied","code":150}}

Iespējamie kļūdu statusa kodi un to atšifrējums:

Kods Kļūdas teksts Paskaidrojums
10 Internal error API sistēmas iekšēja kļūda
20 Service not available API uz laiku nav pieejams
80 Bad request kļūda API pieprasījuma parametros
90 Invalid action norādīta neatļauta action parametra vērtība
101 Invalid user API key norādīta nederīga apikey parametra vērtība (lietotāja API atslēga)
103 Invalid application API key norādīta nederīga app parametra vērtība (aplikācijas API atslēga)
104 IP address not allowed API pieprasījums veikts no datora, kura IP adrese nav starp aplikācijas uzstādījumos atļautajām
105 Max API request limit in 10 minutes reached pārsniegts atļautais API pieprasījumu skaits 10 minūtēs šim lietotājam
106 Invalid or unapproved auth code authorize pieprasījumā izmantots nederīgs vai jau izmantots code parametrs
107 Max activity limit for this user today reached sasniegts maksimālais atļautais nosūtīto profila jaunumu vai aktivitāšu skaits dienā šim lietotājam
120 Data not found pieprasītie dati nav atrasti
130 Spam/Flood detected konstatēta pārāk bieža datu (profila jaunumi, aktivitātes, u.c.) atkārtota sūtīšana
150 Access denied pieprasīti dati, kuriem lietotājam nav piekļuves tiesību

2.3.   Lietotāju dati

Ja API pieprasījumā tiek iegūti dati, kas saistīti ar lietotājiem, tad API atbilde satur bloku users ar iesaistīto lietotāju profilu pamatinformāciju. Katram lietotājam eksistē atribūts uid, kura vērtība ir draugiem.lv lietotāja identifikators, to izmanto lai piesaistītu lietotāja datus citiem objektiem.

Paraugs XML formātā:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        ...
        <users>
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <nick>Janka</nick>
                        <place>Rīga</place>
                        <age/>
                        <adult>1</adult>
                        <img>http://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <sex>M</sex>
                </user>
                ...
        </users>
</draugiem>

Paraugs PHP formātā:

a:1:{s:5:"users";a:1:{i:3342174;a:9:{s:3:"uid";i:3342174;s:4:"name";s:6:"Jānis";s:7:"surname";s:9:"Liepiņš";s:4:"nick";s:5:"janko";s:5:"place";s:14:"Rīga, Latvija";s:3:"age";b:0;s:5:"adult";i:0;s:3:"img";b:0;s:3:"sex";s:1:"F";}}}

Paraugs JSON formātā:

{"users":{"3342174":{"uid":3342174,"name":"J\u0101nis","surname":"Liepi\u0146\u0161","nick":"janko","place":"Latvija","age":false,"adult":0,"img":"http://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg","sex":"M"}}}

Par katru lietotāju ir pieejama šādi informācijas atribūti:

name:lietotāja vārds
surname:lietotāja uzvārds
nick:iesauka
place:dzīvesvieta
age:vecums (tukšs, ja profilā norādīts slēpt vecumu)
adult:norāda, vai lietotājs ir sasniedzis 18 gadu vecumu (1, ja persona ir pilngadīga, 0, ja nav). Ļauj pārbaudīt, vai lietotājs ir pilngadīgs arī tad, ja viņš izvēlējies nerādīt savu vecumu publiski.
img:profila attēla URL (100x100px). Ja lietotājam nav attēla, šis atribūts ir bez vērtības
imgi:profila attēla URL (50x50px).
imgm:profila attēla URL vidējā izmērā (210px platums, augstums mainīgs)
imgl:profila attēla URL maksimālā izmērā (maksimāli 710px platums un 710px augstums)
sex:dzimums (M - vīrietis, F - sieviete)
deleted:ja lietotājs būs dzēsts no draugiem.lv, tad tiks atgriezta vērtība 1, ja tas ir parasts lietotājs, tad 0

2.4.   Paziņojumu saņemšana par lietotājiem, kas dzēsušies no aplikācijas

Aizpildot aplikācijas uzstādījumos parametru Aplikācijas atteikšanās statusa URL, iespējams panākt, ka draugiem.lv izsauc jūsu norādīto adresi ikreiz, kad kāds lietotājs pārtrauc lietot jūsu aplikāciju (nospiežot Atteikties no šīs aplikācijas), vai dzēš savu profilu no portāla.

Tādā veidā aplikācijai iespējams dzēst lietotāja informāciju vai veikt citas darbības, ko nepieciešams veikt, ja lietotājs pārtraucis aplikācijas izmantošanu.

Adresei tiek pievienoti šādi GET parametri:

status:vērtība delete
uid:dzēstā lietotāja ID
app:aplikācijas ID

Piemērs:

Ja aplikācijai ar ID 1234 uzstādīta dzēšanās statusa adrese http://example.com/delete_profile/, tad dzēšoties lietotājam ar ID 12345, tiks izsaukta adrese http://example.com/delete_profile/?status=delete&uid=12345&app=123

Atbildei uz pieprasījumu jāsatur tikai teksts OK, citādi draugiem.lv sistēma uzskatīs, ka aplikācija paziņojumu nav saņēmusi un mēģinās to piegādāt atkārtoti.

3.   Pieejamie API pieprasījumi

3.1.   Lietotāja autorizācija un profila informācijas iegūšana (pieprasījums authorize)

Pieprasījums ļauj iegūt lietotāja API atslēgu, kas nepieciešama pārējo API pieprasījumu veikšanai, kā arī pamatinformāciju par lietotāka profilu.

Pieprasījuma parametri:

action:authorize
app:aplikācijas API atslēga (32 simboli)
code:dr_auth_code vērtība, kas tika saņemta kā GET parametrs pēc lietotāja pieteikšanās (draugiem.lv Pases aplikācijām) vai atverot aplikācijas iframe (integrētajām aplikācijām)

Atbilde uz šo pieprasījumu saturēs šādus elementus:

apikey:lietotāja API atslēga
uid:draugiem.lv lietotāja ID
language:lietotāja portālā uzstādītās valodas divu burtu kods
inviter:tā cilvēka ID, kurš uzaicinājis šo lietotāju pievienoties aplikācijai (šis elements sastopams tikai tad, ja lietotājs pirmo reizi ienācis aplikācijā pēc apstiprināta uzaicinājuma)
invite_extra:papildu dati, kas bijuši piesaistīti apstiprinātajam uzaicinājumam (šis elements sastopams tikai tad, ja lietotājs pirmo reizi ienācis aplikācijā pēc apstiprināta uzaicinājuma)

API atslēga aplikācijai ļaus turpmāk piekļūt lietotāja datiem caur Draugiem.lv API bez vajadzības atkārtoti veikt autorizācijas procesu. Pēc veiksmīgas autorizācijas aplikācija būs redzama portāla sadaļā Manas aplikācijas. No turienes lietotājs varēs apturēt aplikācijas piekļuvi savam profilam.

Atbilde satur arī lietotāja profila pamatinformāciju atbilstoši nodaļā Lietotāju dati aprakstītajam formātam.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <apikey>09797abfe8e5ea53fd857cc372e3a6f5</apikey>
        <uid>491171</uid>
        <language>lv</language>
        <users>
         <user uid="491171">
                 <name>Jānis</name>
                 <surname>Bērziņš</surname>
                 <nick>Janka</nick>
                 <place>Rīga</place>
                 <age/>
                 <adult>1</adult>
                 <img>http://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                 <sex>M</sex>
         </user>
        </users>
</draugiem>

Lai aplikācija varētu piekļūt lietotāja datiem, tai jāiegaumē iegūtā apikey vērtība, un jāizmanto visos turpmākajos API pieprasījumos, norādot to kā parametra apikey vērtību.

Ja aplikācija aizmirsusi lietotāja API atslēgu, vai arī lietotājs to dzēsis no profila, autorizācijas procesu iespējams veikt atkārtoti. Lietotāja API atslēga var mainīties, ja lietotājs nomaina draugiem.lv lietotāja paroli vai dzēš aplikāciju no profila un piesakās tai atkārtoti.

3.2.   Konkrētu aplikācijas lietotāju datu iegūšana (pieprasījums userdata)

Pieprasījums ļauj iegūt pamatinformāciju par atsevišķiem draugiem.lv lietotājiem, kas autorizējuši šo aplikāciju. Šim pieprasījumam nav vajadzīga lietotāja API atslēga, pietiek ar aplikācijas atslēgu.

Pieprasījuma parametri:

action:userdata
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli), nav jānorāda obligāti, ja tiek norādīts ids parametrs
ids:neobligāts parametrs, ar komatu atdalīti draugiem.lv lietotāju ID (maksimums 100 dažādi ID vienā pieprasījumā), kuru dati tiek pieprasīti

Ja pieprasījumā norādīts parametrs ids, atbilde saturēs pamatinformāciju par pieprasītajiem lietotājiem atbilstoši nodaļā Lietotāju dati aprakstītajam formātam. Tiek sniegta tikai informācija par lietotājiem, kas autorizējuši šo aplikāciju (ja lietotājs dzēsis aplikāciju no profila, viņa dati vairs nav pieejami).

Ja netiek norādīts parametrs ids un ir norādīts parametrs apikey, tad tiek atgriezta informācija par lietotāju, kam pieder attiecīgā API atslēga, atbilstoši nodaļā Lietotāju dati aprakstītajam formātam.

Atbildē atgrieztie lietotāju dati nav sakārtoti noteiktā secībā.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users>
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <nick>Janka</nick>
                        <place>Rīga</place>
                        <age/>
                        <adult>1</adult>
                        <img>http://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <type>User_Default</type>
                        <sex>M</sex>
                </user>
                <user uid="64428">
                        <name>Elīna</name>
                        <surname>Ozoliņa</surname>
                        <nick>Čiepa</nick>
                        <place>Valmiera, Talsi</place>
                        <age>16</age>
                        <adult>0</adult>
                        <img>http://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg</img>
                        <type>User_Business</type>
                        <sex>F</sex>
                </user>
        </users>
</draugiem>

Draugiem.lv pases lietošanas gadījumā lietotāja dati var saturēt arī nevis parasta lietotāja datus, bet oficiālas draugiem.lv lapas (www.draugiem.lv/lapas) datus. Lai noteiktu, vai tas ir parasts lietotājs, vai lapa, jāpārbauda type parametrā esošā vērtība. Šobrīd ir iespējamas 2 vērtības:

  • User_Default - parasts lietotājs
  • User_Business - draugiem.lv lapa

3.3.   Aplikācijas lietotāju datu iegūšana (pieprasījums app_users)

Pieprasījums ļauj iegūt pamatinformāciju par visiem draugiem.lv lietotājiem, kas autorizējuši šo aplikāciju. Šim pieprasījumam nav vajadzīga lietotāja API atslēga, pietiek ar aplikācijas atslēgu.

Pieprasījuma parametri:

action:app_users
app:aplikācijas API atslēga (32 simboli)
show:neobligāts parametrs, norādot šo parametru ar vērtību ids, tiks atgriezti tikai atbilstošie draugiem.lv lietotāju ID, nevis pilni lietotāju dati.
page:neobligāts parametrs, lietotāju saraksta lappuse, kas jāatgriež. Nenorādot šo parametru, tiks atgriezta pirmā lappuse.
limit:neobligāts parametrs, lietotāju skaits vienā lappusē, robežās no 1 līdz 200. Nenorādot šo parametru, vienā lappusē būs informācija par 20 lietotājiem.

Ja pieprasījumā nav norādīts parametrs show ar vērtību ids, atbilde saturēs elementu users, kas saturēs lietotāju informāciju atbilstoši nodaļā Lietotāju dati aprakstītajam formātam. Elementam users eksistē atribūts total, kas satur aplikācijas lietotāju skaitu visās lappusēs kopā.

Pieprasījuma atbildes paraugs (ja nav norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users total="2">
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <nick>Janka</nick>
                        <place>Rīga</place>
                        <age/>
                        <adult>1</adult>
                        <img>http://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <sex>M</sex>
                </user>
                <user uid="64428">
                        <name>Elīna</name>
                        <surname>Ozoliņa</surname>
                        <nick>Čiepa</nick>
                        <place>Valmiera, Talsi</place>
                        <age>16</age>
                        <adult>0</adult>
                        <img>http://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg</img>
                        <sex>F</sex>
                </user>
        </users>
</draugiem>

Ja pieprasījumā ir norādīts parametrs show ar vērtību ids, atbilde saturēs elementu userids, kas saturēs elementus uid ar atbilstošajiem draugiem.lv lietotāju ID. Elementam userids eksistē atribūts total, kas satur aplikācijas lietotāju skaitu visās lappusēs kopā.

Pieprasījuma atbildes paraugs (ja ir norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <userids total="45">
                <uid>64428</uid>
                <uid>491171</uid>
                <uid>1524905</uid>
                <uid>134564</uid>
                <uid>234561</uid>
        </userids>
</draugiem>

3.4.   Aplikācijas lietotāju skaita iegūšana (pieprasījums app_users_count)

Pieprasījums ļauj iegūt aplikācijas lietotāju skaitu.

Pieprasījuma parametri:

action:app_users_count
app:aplikācijas API atslēga (32 simboli)

Pieprasījuma atbilde satur elementu usercount, kura vērtība ir lietotāju, kas ir autorizējuši aplikāciju, skaits.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <usercount>312</usercount>
</draugiem>

3.5.   Aplikācijas lietotāju savstarpējo draugu iegūšana (pieprasījums app_friends)

Pieprasījums ļauj iegūt informāciju par aplikācijas lietotāja draugiem, kas izmanto šo pašu aplikāciju.

Pieprasījuma parametri:

action:app_friends
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja, kura draugi jāatgriež, API atslēga (32 simboli)
show:neobligāts parametrs, norādot šo parametru ar vērtību ids, tiks atgriezti tikai atbilstošie draugiem.lv lietotāju ID, nevis pilni lietotāju dati.
page:neobligāts parametrs, draugu saraksta lappuse, kas jāatgriež. Nenorādot šo parametru, tiks atgriezta pirmā lappuse.
limit:neobligāts parametrs, draugu skaits vienā lappusē, robežās no 1 līdz 200. Nenorādot šo parametru, vienā lappusē būs informācija par 20 draugiem.

Ja pieprasījumā nav norādīts parametrs show ar vērtību ids, atbilde saturēs elementu users, kas saturēs lietotāju informāciju atbilstoši nodaļā Lietotāju dati aprakstītajam formātam. Elementam users eksistē atribūts total, kas satur atbilstošo draugu skaitu visās lappusēs kopā.

Pieprasījuma atbildes paraugs (ja nav norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <users total="2">
                <user uid="491171">
                        <name>Jānis</name>
                        <surname>Bērziņš</surname>
                        <nick>Janka</nick>
                        <place>Rīga</place>
                        <age/>
                        <adult>1</adult>
                        <img>http://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg</img>
                        <sex>M</sex>
                </user>
                <user uid="64428">
                        <name>Elīna</name>
                        <surname>Ozoliņa</surname>
                        <nick>Čiepa</nick>
                        <place>Valmiera, Talsi</place>
                        <age>16</age>
                        <adult>0</adult>
                        <img>http://i8.ifrype.com/profile/064/428/v3/sm_64428.jpg</img>
                        <sex>F</sex>
                </user>
        </users>
</draugiem>

Ja pieprasījumā ir norādīts parametrs show ar vērtību ids, atbilde saturēs elementu userids, kas saturēs elementus uid ar atbilstošajiem draugiem.lv lietotāju ID. Elementam userids eksistē atribūts total, kas satur atbilstošo draugu skaitu visās lappusēs kopā.

Pieprasījuma atbildes paraugs (ja ir norādīts show=ids):

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <userids total="45">
                <uid>64428</uid>
                <uid>491171</uid>
                <uid>1524905</uid>
                <uid>134564</uid>
                <uid>234561</uid>
        </userids>
</draugiem>

3.6.   Aplikācijas lietotāja draugu skaita iegūšana (pieprasījums app_friends_count)

Pieprasījums ļauj iegūt aplikācijas lietotāja draugu skaitu, kas izmanto šo pašu aplikāciju.

Pieprasījuma parametri:

action:app_friends_count
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja, kura draugu skaits jāatgriež, API atslēga (32 simboli)

Pieprasījuma atbilde satur elementu friendcount, kura vērtība ir lietotāja draugu skaits, kas lieto aplikāciju.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
    <draugiem>
            <friendcount>16</friendcount>
    </draugiem>

3.7.   Divu lietotāju savstarpējās draudzības pārbaude (pieprasījums check_friendship)

Pieprasījums ļauj pārbaudīt, vai divi aplikācijas lietotāji savā starpā ir draugi.

Pieprasījuma parametri:

action:check_friendship
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli). Šis parametrs nav obligāts, ja tiek norādīts uid2 parametrs
uid:pirmā lietotāja ID
uid2:otrā lietotāja ID. Šis parametrs nav obligāts, ja tiek norādīts apikey parametrs
  • Ja norādīts gan uid, gan uid2 parametrs, tiek atgriezts draudzības statuss starp šiem abiem lietotājiem.
  • Ja nav norādīta uid2 vērtība, bet ir norādīta apikey vērtība, tiek atgriezts draudzības statuss starp apikey īpašnieku un lietotāju ar uid parametrā norādīto ID.
  • API pieprasījuma atbilde satur elementu status, kura vērtība ir OK, ja starp lietotājiem pastāv draudzības saite.
  • Ja starp lietotājiem nepastāv draudzība, status vērtība ir NOT_FRIENDS.
  • Ja kāds no pieprasītajiem lietotājiem nav apstiprināts aplikācijas lietotājs, elementa status vērtība ir NOT_USERS.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <status>OK</status>
</draugiem>

3.8.   Informācijas pievienošana lietotāja profila aktivitātēs (pieprasījums add_activity)

Pieprasījums ļauj pievienot ierakstu ar saiti uz ārēju resursu draugiem.lv lietotāja profila aktivitāšu sarakstā.

Šis pieprasījums nav atļauts visām aplikācijām. Lai iegūtu savai aplikācijai iespēju pievienot informāciju profila aktivitātēs, rakstiet e-pastu uz api@draugiem.lv, kurā pastāstiet par savu aplikāciju un to, kādas profila aktivitātes tā veidos. Integrētajām aplikācijām izstrādes režīmā aktivitāšu pievienošana ir pieejama testēšanas režīmā (tās redzēs tikai aplikācijas izstrādātāji un administratori), bet lai turpinātu aktivitāšu pievienošanu pēc tam, kad aplikācija publicēta, tās jāatļauj no draugiem.lv puses.

Pievienotajai saitei jāved uz to pašu domēnu, kas reģistrēts aplikācijas uzstādījumos.

Pie aktivitātes būs redzama aplikācijas ikona, kas pievienota aplikācijas uzstādījumos. Viena aplikācija var izveidot ne vairāk kā vienu aktivitāti diennaktī katram lietotājam.

img/events.png

Aktivitātēm jābūt atbilstošām šādiem principiem:

  • Aktivitātei jāinformē par konkrētu attiecīgā lietotāja veiktu darbību ārējā resursā.
  • Aktivitāšu sistēmu nedrīkst izmantot reklāmai.
  • Vēlams pirms jauna veida aktivitāšu pievienošanas konsultēties ar draugiem.lv par to atbilstību noteikumiem.
  • Integrētajām aplikācijām saitē jānorāda adrese, kas jāatver iframe logā, nevis aplikācijas adrese draugiem.lv portālā - tā tiks automātiski pārveidota uz pareizo. Jāatceras, ka iframe attēlojamā adrese drīkst saturēt mapes ceļu un GET parametrus, bet ne faila nosaukumu.

Ja tiks konstatēts, ka aplikācija veido neatbilstošas aktivitātes, tai tiks liegta piekļuve aktivitāšu pievienošanai.

Pieprasījuma parametri:

action:add_activity
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
prefix:neobligāts parametrs, teksts, kas redzams profila aktivitātes sākumā, pirms klikšķināmās saites. Maksimālais atļautais garums 50 simboli, garāki teksti tiks saīsināti.
text:klikšķināmās saites teksts profila aktivitātē. Maksimālais atļautais garums 100 simboli, garāki teksti tiks saīsināti.
link:neobligāts parametrs, saite, uz kuru lietotājs aiziet, noklikšķinot uz aktivitātes. Ja šis parametrs nav norādīts, saite vedīs uz aplikācijas uzstādījumos norādīto lapas adresi. Atļauts norādīt tikai saites, kuru domēns ir vienāds ar aplikācijas uzstādījumos norādītās adreses domēnu. Maksimālais garums 100 simboli.
page_id:papildus parametrs lapu aplikācijām, kurā jāpadod lapas identifikators, kurā aplikācija ir ievietota
  • Ja aktivitāte veiksmīgi pievienota, API pieprasījuma atbilde satur elementu status, kura vērtība ir OK.
  • Ja aplikācijai, kas veic pieprasījumu, nav tiesību pievienot aktivitātes, vai arī lietotājs liedzis aplikācijai piekļuvi aktivitātēm, pieprasījums atgriezīs kļūdas kodu 150 (Access denied).
  • Ja jau ir sasniegts lietotājam dienā pievienojamo aktivitāšu limits, pieprasījums atgriezīs kļūdas kodu 107 (Max activity limit for this user today reached)

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <status>OK</status>
</draugiem>

3.9.   Paziņojuma attēlošana lietotāja profila jaunumos (pieprasījums add_notification)

Pieprasījums ļauj pievienot paziņojumu ar saiti lietotāja profila jaunumu blokā, kas atrodas sākumlapā. Šis pieprasījums nav atļauts visām aplikācijām. Lai iegūtu savai aplikācijai iespēju pievienot informāciju profila jaunumos, rakstiet e-pastu uz api@draugiem.lv, kurā pastāstiet par savu aplikāciju un to, kādus paziņojumus tā rādīs. Integrētajām aplikācijām izstrādes režīmā profila jaunumu pievienošana ir pieejama testēšanas režīmā (tos redzēs tikai aplikācijas izstrādātāji un administratori), bet lai turpinātu jaunumu pievienošanu pēc tam, kad aplikācija publicēta, tā jāatļauj no draugiem.lv puses.

Pievienotajai saitei jāved uz to pašu domēnu, kas reģistrēts aplikācijas uzstādījumos.

Pie jaunuma būs redzama aplikācijas ikona, kas pievienota aplikācijas uzstādījumos. Viena aplikācija var pievienot ne vairāk kā piecus profila jaunumus diennaktī katram lietotājam, ne ātrāk kā stundu pēc iepriekšējā jaunuma pievienošanas.

img/profileNews.png

Paziņojumiem jābūt atbilstošām šādiem principiem:

  • Paziņojumam jāinformē par konkrētu notikumu attiecīgā lietotāja aplikācijas profilā, vēlams, lai saite ved uz paziņojuma saturam atbilstošu vietu aplikācijā nevis uz sākumlapu.
  • Paziņojumu sistēmu nedrīkst izmantot, lai bez iemesla reklamētu savu aplikāciju.
  • Vēlams pirms jauna veida paziņojumu izmantošanas konsultēties ar draugiem.lv par to atbilstību noteikumiem.
  • Integrētajām aplikācijām saitē jānorāda adrese, kas jāatver iframe logā, nevis aplikācijas adrese draugiem.lv portālā - tā tiks automātiski pārveidota uz pareizo. Jāatceras, ka iframe attēlojamā adrese drīkst saturēt mapes ceļu un GET parametrus, bet ne faila nosaukumu.

Ja tiks konstatēts, ka aplikācija veido neatbilstošus profila jaunumus, tai tiks liegta piekļuve jaunumu pievienošanai.

Iespējams pievienot gan paziņojumu, kurš nācis no konkrēta lietotāja, gan tādu, kuram kā izraisītājs tiek rādīta pati aplikācija.

Svarīgi: jāatceras, ka paziņojums parādās tam lietotājam, kuram pieder pieprasījumā norādītā API atslēga. Tāpēc, lai parādītu paziņojumu cilvēkam, kurš dotajā brīdī nelieto aplikāciju, aplikācija jāuzglabā viņa API atslēga izmantošanai profila jaunumu pievienošanā.

Pieprasījuma parametri:

action:add_notification
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
prefix:neobligāts parametrs, teksts, kas redzams paziņojuma sākumā, pirms klikšķināmās saites. Maksimālais atļautais garums 50 simboli, garāki teksti tiks saīsināti.
text:klikšķināmās saites teksts profila jaunumos. Maksimālais atļautais garums 100 simboli, garāki teksti tiks saīsināti.
link:neobligāts parametrs, adrese, uz kuru lietotājs aiziet, noklikšķinot uz saites. Ja šis parametrs nav norādīts, saite vedīs uz aplikācijas uzstādījumos norādīto lapas adresi. Atļauts norādīt tikai saites, kuru domēns ir sakrīt ar aplikācijas uzstādījumos norādītās adreses domēnu. Maksimālais garums 100 simboli.
creator:neobligāts parametrs, lietotāja ID, kurš tiek attēlots kā profila jaunuma izraisītājs. Šim lietotājam jābūt aktīvam aplikācijas lietotājam. Ja šis parametrs nav norādīts, kā jaunuma autors tiks attēlota aplikācija.
  • Ja paziņojums ir pievienots, API pieprasījuma atbilde satur elementu status, kura vērtība ir OK.
  • Ja aplikācijai, kas veic pieprasījumu, nav tiesību pievienot profila jaunumus, vai arī lietotājs liedzis aplikācijai piekļuvi profila jaunumiem, pieprasījums atgriezīs kļūdas kodu 150 (Access denied).
  • Ja jau ir sasniegts lietotājam dienā pievienojamo profila jaunumu limits, pieprasījums atgriezīs kļūdas kodu 107 (Max activity limit for this user today reached)
  • Ja kopš iepriekšējāp ievienotā jaunuma nav pagājusi vismaz stunda, pieprasījums atgriezīs kļūdas kodu 130 (Spam/Flood detected)

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <status>OK</status>
</draugiem>

3.10.   Aplikācijas statistikas datu iegūšana (pieprasījums app_status)

Pieprasījums ļauj iegūt statistisku informāciju par aplikācijas darbību.

Pieprasījuma parametri:

action:app_status
app:aplikācijas API atslēga (32 simboli)

Pieprasījuma atgriež šādus statistikas parametrus

users:Kopējais aplikācijā reģistrēto lietotāju skaits
users24h:Aplikācijas aktīvo lietotaju skaits pēdējā diennaktī (atjaunojas reizi stundā)
online:Aplikācijas online lietotāju skaits pēdējās 5 minūtēs
api_rq:Aplikācijas API pieprasījumu skaits sekundē (vidējā vērtība pēdējās 20 sekundēs)
activities:Aplikācijas pievienotās draugu aktivitātes pēdējā minūtē
notifications:Aplikācijas pievienotie profila jaunumi pēdējā minūtē

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <status>
                <users>159552</users>
                <users24h>42872</users24h>
                <online>1340</online>
                <api_rq>33.25</api_rq>
                <activities>15</activities>
                <notifications>8</notifications>
        </status>
</draugiem>

3.11.   Ieraksta pievienošana kalendārā

Pieprasījums ļauj pievienot ierakstu (piezīmi) kalendārā.

Pieprasījuma parametri:

action:calendar/add
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
text:piezīmes teksts
start_time:sākuma laiks (skaitliska vērtība - timestamp)
end_time:beigu laiks (skaitliska vērtība - timestamp)
allday:notikums ilgs visu dienu. Neobligāts parametrs. Iespējamās vērtības - 1, 0
repeat:piezīmes atkārtošanās biežums. Neobligāts parametrs. Iespējamās vērtības - daily, workdays, weekly, monthly, yearly

Pieprasījuma atbildes paraugs pēc veiksmīgi pievienota ieraksta:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <status>OK</status>
</draugiem>

4.   Draugiem.lv API PHP bibliotēka

Lai aplikāciju izstrādi padarītu ātrāku un vienkāršāku, esam izveidojuši PHP bibliotēku, kas veic API izsaukumus un automātiski pārveido pieprasītos datus uz PHP datu struktūrām. PHP bibliotēka var tikt izmantota gan portālā integrētajām aplikācijām, gan draugiem.lv Pases aplikācijām.

PHP bibliotēkas dokumentācija

Draugiem.lv API PHP bibliotēka un izmantošanas paraugi