Draugiem.lv Lapu Administrācijas API

1.   Ievads

Draugiem.lv lapas ir modulārs un viegli paplašināms risinājums, kas ļauj katram draugiem.lv lietotājam veidot mājas lapas, kas atbilst viņa vajadzībām. Līdz šim visi draugiem.lv lapu administrēšanas darbi bija jāveic caur draugiem.lv vidi, kas nozīmēja, ka bija visai lielas iespējas palaist garām kādu svarīgu vēstuli, uzdoto jautājumu vai kādu citu niansi. Esam uzbūvējuši Draugiem.lv lapu administrēšanas API, kas ļauj piekļūt lapu pamatinformācijai, ļauj lasīt uzdotos jautājumus, atbildēt uz tiem, pievienot jaunus ierakstus jaunumu plūsmā, u.c.

Pēc noklusējuma visām lapām API iespējas ir izslēgtas, katra lapa pati var tās ieslēgt ieslēdzot administrēšanas režīmu un izvēloties sadaļu "Lapas API". Pēc tam, kad API ir pieslēgts, ir iespējams pievienot arī papildus lietotājus, kas varēs darboties lapas API. Tālāk izmantojot ekrānā redzamo lapas aplikācijas ID, lapas atslēgu un attiecīgā lietotāja atslēgu jau var darboties ar konkrētiem API pieprasījumiem, izmantojot draugiem.lv PHP API bibliotēku:

<?php
        $pagesapi = new DraugiemAPI($appid, $appkey, $userkey);
        var_dump($pagesapi -> apiCall('pages/dashboard'));

Rezultāts:

array(13) {
  ["pageviews"]=>
  string(1) "1"
  ["pageviews_week"]=>
  string(2) "23"
  ["unique_pageviews"]=>
  string(1) "1"
  ["unique_pageviews_week"]=>
  string(2) "14"
  ["fans"]=>
  int(2)
  ["fansdelta"]=>
  int(0)
  ["fansdelta_week"]=>
  NULL
  ["received_messages"]=>
  int(5)
  ["unread_messages"]=>
  int(0)
  ["sent_messages"]=>
  int(0)
  ["answered_faq"]=>
  string(1) "0"
  ["unanswered_faq"]=>
  string(1) "0"
  ["oldest_unanswered_faq"]=>
  bool(false)
}

2.   Pieejamie API pieprasījumi

2.1.   Lapas aktuālās informācijas iegūšana (pages/dashboard izsaukums)

Ar šo izsaukumu iespējams pieprasīt informāciju par lapas statistikas kopsavilkumu. Tas parāda datus par apmeklētājiem, vēstulēm, jautājumiem u.c.

Pieprasījuma parametri:

action:pages/dashboard
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <pageviews>65</pageviews>
        <pageviews_week>400</pageviews_week>
        <unique_pageviews>3</unique_pageviews>
        <unique_pageviews_week>11</unique_pageviews_week>
        <fans>1</fans>
        <fansdelta>0</fansdelta>
        <fansdelta_week>1</fansdelta_week>
        <received_messages>0</received_messages>
        <unread_messages>0</unread_messages>
        <sent_messages>0</sent_messages>
        <answered_faq>1</answered_faq>
        <unanswered_faq>3</unanswered_faq>
        <oldest_unanswered_faq>2011-06-20 11:13:12</oldest_unanswered_faq>
</draugiem>

Atbildes parametru skaidrojums:

pageviews apmeklējumu skaits šodien
pageviews_week apmeklējumu skaits šonedēļ
unique_pageviews unikālo apmeklētāju skaits šodien
unique_pageviews_week unikālo apmeklētāju skaits šonedēļ
fans sekotāju skaits
fansdelta sekotāju izmaiņas šodien
fansdelta_week sekotāju izmaiņas šonedēļ
received_messages saņemtās vēstules
unread_messages nelasītās vēstules
sent_messages nosūtītās vēstules
answered_faq atbildētie jautājumi
unanswered_faq neatbildētie jautājumi
oldest_unanswered_faq vecākā neatbildētā jautājuma datums

2.2.   Lapu jaunumu administrēšana (izsaukums pages/news)

Izsaukums, kas ļauj apskatīt, pievienot un dzēst lapas jaunumus. Izsaukumam ir 4 dažādas metodes - list, add, edit un delete.

2.2.1.   Metode list

Pieprasījuma parametri:

action:pages/news
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:list
cat:jaunumu kategorija, kuras ierakstus atgriezt (neobligāts)

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <posts>
                <post id="5082842">
                        <title>Jaunuma virsraksts</title>
                        <text>Jaunuma teksts</text>
                        <draft>1</draft>
                        <image>http://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg</image>
                        <imageicon>http://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg</imageicon>
                        <imagesmall>http://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg</imagesmall>
                        <imagemiddle>http://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg</imagemiddle>
                        <comments>13</comments>
                        <likes>23</likes>
                        <created>2011-06-17 12:13:46</created>
                        <category>0</category>
                </post>
        </posts>
</draugiem>

Elements draft norāda uz to, vai jaunums ir melnraksts vai nav. Elements image satur informāciju par jaunuma titulbildes adresi – ja vērtība ir 0, tad titulbildes nav.

2.2.2.   Metode add

Pieprasījuma parametri:

action:pages/news
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:add
title:jaunuma virsraksts
text:jaunuma teksts
draft:atzīme par to, vai jaunums ir melnraksts (vērtības 0 un 1)
image_data:titulbildes attēls. Datus nepieciešams sagatavot base64 kodējumā. (parametrs nav obligāts)
comments:atzīme par to, vai atļaut komentārus pie šī jaunuma (vērtības 0 un 1)

Piebilde: Pieprasījums obligāti jāizpilda kā POST pieprasījums.

Pieprasījuma atbildes paraugs:

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

Elements status norāda uz to, vai jaunums ir veiksmīgi pievienots. Ja tā ir, tad elementa vērtība ir OK. Pretējā gadījumā vērtība ir ERROR.

2.2.3.   Metode edit

Pieprasījuma parametri:

action:pages/news
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:edit
id:rediģējamās ziņas ID
title:jaunuma virsraksts
text:jaunuma teksts
draft:atzīme par to, vai jaunums ir melnraksts (vērtības 0 un 1)
image_data:titulbildes attēls. Datus nepieciešams sagatavot base64 kodējumā. (parametrs nav obligāts)
delete_image:Ja parametra vērtība ir 1, tad titulbilde tiks dzēsta
comments:atzīme par to, vai atļaut komentārus pie šī jaunuma (vērtības 0 un 1)

Piebilde: Pieprasījums obligāti jāizpilda kā POST pieprasījums. Vienīgais obligātais parametrs ir ID. Pārējos var norādīt atkarībā no nepieciešamības tos mainīt.

Pieprasījuma atbildes paraugs:

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

Elements status norāda uz to, vai jaunums ir veiksmīgi pievienots. Ja tā ir, tad elementa vērtība ir OK. Pretējā gadījumā vērtība ir ERROR.

2.2.4.   Metode get

Pieprasījuma parametri:

action:pages/news
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:get
id:jaunuma ID

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <posts>
                <post id="5082842">
                        <title>Jaunuma virsraksts</title>
                        <text>Jaunuma teksts</text>
                        <draft>1</draft>
                        <image>http://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg</image>
                        <imageicon>http://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg</imageicon>
                        <imagesmall>http://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg</imagesmall>
                        <imagemiddle>http://i9.ifrype.com/posts/248/559/v1311070256/l_5248551.jpg</imagemiddle>
                        <comments>13</comments>
                        <likes>23</likes>
                        <created>2011-06-17 12:13:46</created>
                </post>
        </posts>
</draugiem>

2.2.5.   Metode delete

Pieprasījuma parametri:

action:pages/news
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:delete
id:jaunuma ID

Pieprasījuma atbildes paraugs:

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

Elements status norāda uz to, vai jaunums ir veiksmīgi izdzēsts. Ja tā ir, tad elementa vērtība ir OK. Pretējā gadījumā vērtība ir ERROR.

2.3.   Jautājumu un atbilžu administrēšana (izsaukums pages/faq)

Izsaukums, kas ļauj apskatīt jautājumus, atbildēt uz tiem un tos dzēst. Izsaukumam ir 3 dažādas metodes - list, answer un delete.

2.3.1.   Metode list

Pieprasījuma parametri:

action:pages/faq
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:list

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <faq>
                <question id="14094">
                        <question>Jautājuma teksts</question>
                        <answer>Atbilde uz jautājumu</answer>
                        <created>2011-06-17 12:13:46</created>
                        <status>1</status>
                        <uid>1</uid>
                </question>
        </faq>
</draugiem>

Elements status norāda uz to, vai ir sagatavota atbilde uz jautājumu. Ja atbilde ir, tad statusa vērtība ir 1. Elements uid satur informāciju par draugiem.lv lietotāju, kur uzdevis jautājumu.

2.3.2.   Metode answer

Pieprasījuma parametri:

action:pages/faq
app:Alikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:answer
question_id:jautājuma identifikators
answer:Atbildes teksts

Pieprasījuma atbildes paraugs:

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

Elements status norāda uz to, vai atbilde ir veiksmīgi pievienota. Ja tā ir, tad elementa vērtībā ir OK. Pretējā gadījumā vērtība ir ERROR.

2.3.3.   Metode delete

Pieprasījuma parametri:

action:pages/faq
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:delete
question_id:jautājuma identifikators

Pieprasījuma atbildes paraugs:

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

Elements status norāda uz to, vai jautājums ir veiksmīgi izdzēsts. Ja tā ir, tad elementa vērtībā ir OK. Pretējā gadījumā vērtība ir ERROR.

2.4.   Lapas statistikas dati (pages/stats izsaukums)

Ar šo izsaukumu iespējams pieprasīt informāciju par lapas statistiku dažādos laika periodos. Izsaukumam ir 4 dažādi griezumi, kuri tiek norādīti ar parametru type - unique, fans, pages, genders.

2.4.1.   Griezums unique

Pieprasījums parāda datus par unikālajiem apmeklētājiem.

Pieprasījuma parametri:

action:pages/stats
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
type:unique
date_from:sākuma datums formā YYYY-MM-DD (nav obligāts)
date_till:beigu datums formā YYYY-MM-DD (nav obligāts)
total:ja tiek padots šis parametrs, tad tiek atgriezts kopējais unikālo lietotāju skaits par norādīto periodu (nav obligāts)

Ja netiek norādīti datumi, tad tiek parādīta statistika par tekošo mēnesi.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <unique>
                <day date="2011-06-21">123</day>
                <day date="2011-06-22">33</day>
                <day date="2011-06-23">42</day>
                <day date="2011-06-24">47</day>
                <day date="2011-06-25">77</day>
                <day date="2011-06-26">38</day>
                <day date="2011-06-27">144</day>
                <day date="2011-06-28">299</day>
        </unique>
</draugiem>

Pieprasījuma atbildes paraugs, ja padots "total" parametrs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <unique>123</unique>
</draugiem>

2.4.2.   Griezums fans

Pieprasījums parāda fanu skaita dinamikas datus.

Pieprasījuma parametri:

action:pages/stats
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
type:fans
date_from:sākuma datums formā YYYY-MM-DD (nav obligāts)
date_till:beigu datums formā YYYY-MM-DD (nav obligāts)

Ja netiek norādīti datumi, tad tiek parādīta statistika par tekošo mēnesi.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <fans>
                <day date="2011-06-21">22</day>
                <day date="2011-06-22">23</day>
                <day date="2011-06-23">25</day>
                <day date="2011-06-24">33</day>
                <day date="2011-06-25">46</day>
                <day date="2011-06-26">68</day>
                <day date="2011-06-27">132</day>
                <day date="2011-06-28">256</day>
        </fans>
</draugiem>

2.4.3.   Griezums pages

Pieprasījums parāda sadaļu skatījumu datus.

Pieprasījuma parametri: :action: pages/stats :app: aplikācijas API atslēga (32 simboli) :apikey: lietotāja API atslēga (32 simboli) :type: pages :date_from: sākuma datums formā YYYY-MM-DD (nav obligāts) :date_till: beigu datums formā YYYY-MM-DD (nav obligāts)

Ja netiek norādīti datumi, tad tiek parādīta statistika par tekošo mēnesi.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <pages>
                <day date="2011-06-21">
                        <firstpage>324</firstpage>
                        <fans>57</fans>
                        <faq>12</faq>
                        <guestbook>7</guestbook>
                </day>
        </pages>
</draugiem>

Elementu skaidrojumi:

firstpage:pirmā lapa
fans:fanu lapa
faq:biežāk uzdotie jautājumi
guestbook:viesu grāmata
say:runā sadaļa
gallery:galeriju sadaļa
news:jaunumu sadaļa
pages:teksta lapas

Līdz ar draugiem.lv lapu funkcionalitātes paplašināšanu šiem elementiem var pievienoties jauni.

2.4.4.   Griezums genders

Pieprasījums parāda datus par apmeklētāju vecumu un dzimumu.

Pieprasījuma parametri:

action:pages/stats
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
type:genders
date_from:sākuma datums formā YYYY-MM-DD (nav obligāts)
date_till:beigu datums formā YYYY-MM-DD (nav obligāts)

Ja netiek norādīti datumi, tad tiek parādīta statistika par tekošo mēnesi.

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <genders>
                <item age="36">
                        <men>30</men>
                        <women>38</women>
                </item>
        </genders>
</draugiem>

Tiek atgriezti 100 item elementi – attiecīgi statistika par lietotājiem vecumā no 1 – 100 gadiem.

2.5.   Lapas runā plūsmas pārvaldība (pages/say izsaukums)

Ar šo izsaukumu ir iespējams iegūt lapas runā plūsmu, kā arī pievienot jaunus ierakstus un dzēst esošos

2.5.1.   Metode list

Pieprasījums atgriež lapas runā plūsmu

Pieprasījuma parametri:

action:pages/say
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:list
filter:all (neobligāts parametrs)

Ja filter parametrs nebūs norādīts, tad tiks atgriezti tikai manuāli pievienotie Runā ieraksti. Ja būs - tiks atgriezti visi ieraksti (t.s. ieraksti par jaunajām galerijām, jaunumu ierakstiem utt.)

Pieprasījuma atbildes paraugs:

<?xml version="1.0" encoding="UTF-8"?>
<draugiem>
        <posts>
                <post id="228218873">
                        <text>Mans teksts</text>
                        <title>Saites teksts</title>
                        <titlePrefix>Ieraksta prefikss</titlePrefix>
                        <recommends>Ieteikumu skaits</recommends>
                        <comments>Komentāru skaits</comments>
                        <created>Izveidošanas laiks</created>
                        <link>Ieraksta links</link>
                </post>
        </posts>
</draugiem>

2.5.2.   Metode add

Pieprasījums jauna runā ieraksta pievienošanai.

Pieprasījuma parametri:

action:pages/say
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:add
titlePrefix:ieraksta prefikss (tiek attēlots oranžā krāsā, attēlā #1)
title:saites teksts (attēlā 2)
link:URL uz kurieni pārsūtīt lietotāju (attēlā 3)
text:Ieraksta teksts (attēlā 4)
age_from:Minimālais lietotāju vecums, kuriem ieraksts būs redzams (nav obligāts)
age_to:Maksimālais lietotāju vecums, kuriem ieraksts būs redzams (nav obligāts un tiks ņemts vērā tikai tad, ja norādīts age_from)
image_data:Pievienotais attēls. Datus nepieciešams sagatavot base64 kodējumā. (parametrs nav obligāts)
img/say_parts.png

Piebilde: ja vēlaties ierakstā pievienot saiti, tad obligāti jānorāda gan title, gan link parametri.

Pieprasījuma atbildes paraugs:

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

Elements status norāda uz to, vai ieraksts ir veiksmīgi pievienots. Ja tā ir, tad elementa vērtībā ir OK. Pretējā gadījumā vērtība ir ERROR.

2.5.3.   Metode delete

Pieprasījums ļauj dzēst kādu runā ierakstu savā runā plūsmā.

Pieprasījuma parametri:

action:pages/say
app:aplikācijas API atslēga (32 simboli)
apikey:lietotāja API atslēga (32 simboli)
method:delete
id:runā ieraksta identifikators

Pieprasījuma atbildes paraugs:

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

Elements status norāda uz to, vai ieraksts ir veiksmīgi pievienots. Ja tā ir, tad elementa vērtībā ir OK. Pretējā gadījumā vērtība ir ERROR.