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:

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:

https://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>
                        <age/>
                        <adult>1</adult>
                        <img>https://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:

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>
                        <age/>
                        <adult>1</adult>
                        <img>https://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:7:{s:3:"uid";i:3342174;s:4:"name";s:6:"Jānis";s:7:"surname";s:9:"Liepiņš";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","age":false,"adult":0,"img":"https://i1.ifrype.com/profile/491/171/v3/sm_491171.jpg","sex":"M"}}}

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

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:

Piemērs:

Ja aplikācijai ar ID 1234 uzstādīta dzēšanās statusa adrese https://example.com/delete_profile/, tad dzēšoties lietotājam ar ID 12345, tiks izsaukta adrese https://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.