Aplikācijas

API lietošana

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>

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

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

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.