Interfejs komunikacji z serwisem

Serwis http://a.pinger.pl udostępnia część swojej funkcjonalności programistom w postaci Application Programming Interface (API) - interfejsu komunikacji z serwisem.

Informacje o aktualizacji API znajdziecie na tym blogu.

Założenia

Autoryzacja

  • Pinger.pl wspiera protokół HTTP Basic Authentication.

Zasoby RESTful

  • Pinger.pl stosuje RESTful. Oznacza to, że zmieniając rozszerzenie w URLu otrzymamy zupełnie nowy format danych.
  • Pinger obsługuje formaty: XML, RSS, Atom, JSON i JS.
  • W opisie metod zaznaczono, jakie formaty są obsługiwane przez te metody.

Parametry

  • Parametry muszą być zakodowane w UTF-8 w postaci URL encode.

Zapytania HTTP

  • Domyślnie wszystkie żądania są typu GET.
  • Zapytania, które dodają wpisy lub komentarze są typu POST.

Kody HTTP

  • API używa kodów HTTP w odpowiedzi na każde zapytanie klienta np.
    • 200 - gdy wpis zostanie dodana do bazy danych,
    • 400 - gdy nastąpiła próba uzyskania danych w nieznanym formacie,
    • 401 - gdy wystąpi błąd autoryzacji,
    • 403 - gdy nastąpi próba dostępu do zasobu wymagającego autoryzacji bez podania loginu i hasła,
    • 404 - gdy wysłano zapytanie o nieistniejącego użytkownika lub wpis,
    • 412 - gdy podano błędny format parametrów lub nie podano parametru callback przy formacie js
  • Formaty zwracanych komunikatów omówiono w części "Metody użytkowników zarejestrowanych"

Metody

Format metod

  • http://a.pinger.pl/<metoda>.<format>/[?<parametry>]
  • format - jeden z: xml, rss, atom, json, js
  • Jeżeli nie zaznaczono inaczej, wszystkie parametry są wymagane

Metody użytkowników anonimowych

Metody te nie wymagają autoryzacji.

authorize

  • funkcjonalność: informuje, czy przesłany login i hasło jest poprawne
  • url: http://a.pinger.pl/authorize.format
  • metoda: POST
  • formaty: xml, json, js (wymagany parametr callback)
  • parametry:
    • username - login użytkownika
    • userpassword - hasło użytkownika
  • przykłady:

    http://a.pinger.pl/authorize.xml

    <ok/>

    http://a.pinger.pl/authorize.json

    {'error':''}

public timeline

  • funkcjonalność: zwraca 10 ostatnich wpisów
  • url: http://a.pinger.pl/public_timeline.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/public_timeline.xml/?page=2

    http://a.pinger.pl/public_timeline.js/?callback=nazwa_funkcji&page=2

friends' timeline

  • funkcjonalność: zwraca 10 ostatnich wpisów znajomych podanego użytkownika,
  • url: http://a.pinger.pl/friends_timeline.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • user - nazwa użytkownika, którego znajomych wpisy chcemy wyświetlić;
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/friends_timeline.xml/?page=2&user=ping

    http://a.pinger.pl/friends_timeline.js/?callback=nazwa_funkcji&user=ping

user's timeline

  • funkcjonalność: zwraca 10 ostatnich wpisów podanego użytkownika
  • url: http://a.pinger.pl/user_timeline.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • user - nazwa użytkownika, którego wiadomości chcemy wyświetlić
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/user_timeline.xml/?page=2&user=ping

    http://a.pinger.pl/user_timeline.js/?callback=nazwa_funkcji&user=ping

discussion timeline

  • funkcjonalność: zwraca 10 ostatnich skomentowanych wpisów dla podanego użytkownika
  • url: http://a.pinger.pl/discussion_timeline.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • user - nazwa użytkownika, którego dyskusje (wpisy własne i skomentowane) chcemy wyświetlić
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/discussion_timeline.xml/?page=2&user=ping

    http://a.pinger.pl/discussion_timeline.js/?callback=nazwa_funkcji&user=ping

observers timeline

  • funkcjonalność: zwraca 10 ostatnich wpisów użytkowników obserwowanych
  • url: http://a.pinger.pl/observers_timeline.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • user - nazwa użytkownika obserwującego
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/observers_timeline.xml/?page=2&user=ping

    http://a.pinger.pl/observers_timeline.js/?callback=nazwa_funkcji&user=ping

show message

  • funkcjonalność: zwraca wiadomość o podanym mid
  • url: http://a.pinger.pl/show_message.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • mid - identyfikator wiadomości
  • przykłady:

    http://a.pinger.pl/show_message.xml/?mid=15

    http://a.pinger.pl/show_message.js/?calback=nazwa_funkcji&mid=15

get messages by tag

  • funkcjonalność: zwraca wiadomości z podanym tagiem
  • url: http://a.pinger.pl/get_user_messages_by_tag.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • tag - tag (wielowyrazowe tagi powinny zawierać znak '+' zamiast spacji)
    • user - nazwa użytkownika, którego wiadomości chcemy wyświetlić
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/get_user_messages_by_tag.xml/?tag=muzyka&user=ping

    http://a.pinger.pl/get_user_messages_by_tag.js/?callback=nazwa_funkcji&tag=muzyka&user=ping

get last comments

  • funkcjonalność: zwraca 10 ostatnich komentarzy dodanych do wpisow na blogu użytkownika 'user'
  • url: http://a.pinger.pl/get_last_comments.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • user - login właściciela bloga
  • przykłady:

    http://a.pinger.pl/get_comments.xml/?user=ping

    http://a.pinger.pl/get_comments.js/?callback=nazwa_funkcji&user=ping

add comment

  • funkcjonalność: dodaje komentarz do wiadomości
  • url: http://a.pinger.pl/add_comment.format
  • metoda: POST
  • formaty: xml, json, js (wymagany paramert callback)
  • parametry:
    • mid - identyfikator wiadomości
    • text - treść komentarza (maksymalnie 1000 znaków)
    • guest (opcjonalnie) - pseudonim

get friends list

  • funkcjonalność: zwraca listę znajomych danego użytkownika
  • url: http://a.pinger.pl/get_friends_list.format
  • metoda: GET
  • formaty: xml, json, js (wymagany paramert callback)
  • parametry:
    • user - nazwa użytkownika, którego znajomych chcemy wyświetlić
  • przykłady:

    http://a.pinger.pl/get_friends_list.xml/?user=ping

    http://a.pinger.pl/get_friends_list.js/?callback=nazwa_funkcji&user=ping

search user

  • funkcjonalność: zwraca 25 użytkowników, których login, pseudonim lub miasto pasują do szukanego wzorca
  • url: http://a.pinger.pl/search_user.format
  • metoda: GET
  • formaty: xml, json, js (wymagany parametr callback)
  • parametry:
    • user - szukana fraza: login, psudonim, miasto
    • page(opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/search_user.xml/?user=ping

    http://a.pinger.pl/search_user.js/?callback=nazwa_funkcji&user=ping

get comments

  • funkcjonalność: zwraca komentarze do podanej wiadomości
  • url: http://a.pinger.pl/get_comments.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • mid - identyfikator wiadomości
  • przykłady:

    http://a.pinger.pl/get_comments.xml/?mid=15

    http://a.pinger.pl/get_comments.js/?callback=nazwa_funkcji&mid=15

get user messages by tag

  • funkcjonalność: zwraca wiadomości uzytkownika z podanym tagiem
  • url: http://a.pinger.pl/get_user_messages_by_tag.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • tag - tag (wielowyrazowy tag powinien zawierać znak '+' zamiast spacji)
    • user (opcjonalnie, domyślnie własne wiadomości) - nazwa użytkownika, którego wiadomości chcemy wyświetlić
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/get_user_messages_by_tag.xml/?tag=muzyka&user=ping

    <?xml version="1.0" encoding="UTF-8"?>
    <statuses>
      <status>
        // tak jak w przypadku [auth_]show_message.xml //
      </status>
      <status>
        ...
      </status>
      ...
    </statuses>

    http://a.pinger.pl/get_user_messages_by_tag.js/?callback=nazwa_funkcji&tag=muzyka&user=ping

    nazwa_funkcji([
      {
        // tak jak w przypadku [auth_]show_message.js //
      },
      {
        ...
      },
      ...
    ])

search messages by tag

  • funkcjonalność: zwraca wiadomości z podanym tagiem (wyszukiwanie globalne)
  • url: http://a.pinger.pl/search_messages_by_tag.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • tag - tag (wielowyrazowe tagi powinny zawierać znak '+' zamiast spacji)
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/auth_search_messages_by_tag.xml/?tag=muzyka

    <?xml version="1.0" encoding="UTF-8"?>
    <statuses>
      <status>
        // tak jak w przypadku [auth_]show_message.xml //
      </status>
      <status>
        ...
      </status>
      ...
    </statuses>

    http://a.pinger.pl/auth_search_messages_by_tag.js/?callback=nazwa_funkcji&tag=muzyka

    nazwa_funkcji([
      {
        // tak jak w przypadku [auth_]show_message.js //
      },
      {
        ...
      },
      ...
    ])

search messages by tags

  • funkcjonalność: zwraca wiadomości oznaczone przynajmniej jednym z podanych tagów (wyszukiwanie globalne)
  • url: http://a.pinger.pl/search_messages_by_tags.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • tag - tags (może być użyte wielokrotnie, patrz przykład)
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/search_messages_by_tag.xml/?tag=muzyka&tag=film

    <?xml version="1.0" encoding="UTF-8"?>
    <statuses>
      <status>
        // tak jak w przypadku [auth_]show_message.xml //
      </status>
      <status>
        ...
      </status>
      ...
    </statuses>

    http://a.pinger.pl/search_messages_by_tag.js/?callback=nazwa_funkcji&tag=muzyka&tag=film

    nazwa_funkcji([
      {
        // tak jak w przypadku [auth_]show_message.js //
      },
      {
        ...
      },
      ...
    ])

search messages

  • funkcjonalność: zwraca wiadomości, w których treści lub kometnarzach znajduje się podana fraza
  • url: http://a.pinger.pl/search_messages.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • text - szukana fraza
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/search_messages.xml/?tag=muzyka&tag=film

    <?xml version="1.0" encoding="UTF-8"?>
    <statuses>
      <status>
        // tak jak w przypadku [auth_]show_message.xml //
      </status>
      <status>
        ...
      </status>
      ...
    </statuses>

    http://a.pinger.pl/search_messages.js/?callback=nazwa_funkcji&text=muzyka

    nazwa_funkcji([
      {
        // tak jak w przypadku [auth_]show_message.js //
      },
      {
        ...
      },
      ...
    ])

Metody użytkowników zarejestrowanych

Metody te wymagają autoryzacji.

auth public timeline

  • funkcjonalność: zwraca 10 ostatnich wpisów
  • url: http://a.pinger.pl/auth_public_timeline.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/auth_public_timeline.xml/?page=2

    <?xml version="1.0" encoding="UTF-8"?>
    <statuses>
      <status>
        // tak jak w przypadku [auth_]show_message.xml //
      </status>
      <status>
        ...
      </status>
      ...
    </statuses>

    http://a.pinger.pl/auth_public_timeline.js/?callback=nazwa_funkcji&page=2

    nazwa_funkcji([
      {
        // tak jak w przypadku [auth_]show_message.js //
      },
      {
        ...
      },
      ...
    ])

auth friends' timeline

  • funkcjonalność: zwraca 10 ostatnich wpisów znajomych użytkownika,
  • url: http://a.pinger.pl/auth_friends_timeline.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • user (opcjonalnie, domyślnie własne) - nazwa użytkownika, którego znajomych wpisy chcemy wyświetlić;
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/auth_friends_timeline.xml/?page=2&user=ping

    http://a.pinger.pl/auth_friends_timeline.js/?callback=nazwa_funkcji&user=ping

auth user's timeline

  • funkcjonalność: zwraca 10 ostatnich wpisów zalogowanego użytkownika lub użytkownika podanego w opcjonalnym parametrze user;
  • url: http://a.pinger.pl/auth_user_timeline.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • user (opcjonalnie, domyślnie własne wpisy) - nazwa użytkownika, którego wiadomości chcemy wyświetlić;
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/auth_user_timeline.xml/?page=2

    http://a.pinger.pl/auth_user_timeline.js/?callback=nazwa_funkcji&user=ping

auth discussion timeline

  • funkcjonalność: zwraca 10 ostatnich skomentowanych wpisów dla zalogowanego użytkownika lub użytkownika podanego w opcjonalnym parametrze user;
  • url: http://a.pinger.pl/auth_discussion_timeline.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • user (opcjonalnie, domyślnie własne dyskusje) - nazwa użytkownika, którego dyskusje (wpisy własne i skomentowane) chcemy wyświetlić
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/auth_discussion_timeline.xml/?page=2&user=ping

    http://a.pinger.pl/auth_discussion_timeline.js/?callback=nazwa_funkcji&user=ping

auth observers timeline

  • funkcjonalność: zwraca 10 ostatnich wpisów użytkowników obserwowanych
  • url: http://a.pinger.pl/auth_observers_timeline.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • user (opcjonalnie, domyślnie własne obserwacje) - nazwa użytkownika obserwującego
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/auth_observers_timeline.xml/?page=2&user=ping

    http://a.pinger.pl/auth_observers_timeline.js/?callback=nazwa_funkcji&user=ping

auth show message

  • funkcjonalność: zwraca wiadomość o podanym mid
  • url: http://a.pinger.pl/auth_show_message.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • mid - identyfikator wiadomości
  • przykłady:

    http://a.pinger.pl/auth_show_message.xml/?mid=15

    <?xml version="1.0" encoding="UTF-8"?>
    <status>
      <created_at>2008-01-05 09:13:16</created_at>
      <published_at>2008-01-15 12:00:00</published_at>
      <modified_at>2008-01-05 16:10:06</modified_at>
      <mid>15</mid>
      <cite>13</cite>
      <text>Test &amp; test Pinga na Pinger.pl</text>
      <title>tytuł wpisu</title>
      <user>
        // autor; tak jak w przypadku [auth_]search_user.xml //
      </user>
      // jeśli jest to wpis na cudzym blogu, dodatkowo:
        <owner>
          // tak jak w przypadku powyższego elementu 'user' //
        </owner>
      <images>
        <image title="smaller.gif" path="http://..." thumb="http://..." fid="101"/>
        <image title="bigfoot.png" path="http://..." thumb="http://..." fid="102"/>
      </images>
      <files>
        <file title="pinger.avi" path="http://..." fid="103"  type="video" mime="video/x-msvideo" size="289280"/>
        <file title="dog.avi" path="http://..." fid="104"  type="video" mime="video/x-msvideo" size="152800"/>
      </files>
      <tags>
        <tag>testy</tag>
        <tag>ping</tag>
      </tags>
      <maps>
    	<map>
    		<point>52.281602,20.874023</point>
    		<zoom>6</zoom>
    		<desc>opis mapy</desc>
    	</map>
      </maps>
      <comments_count>2</comments_count>
    </status>

    http://a.pinger.pl/auth_show_message.js/?callback=nazwa_funkcji&mid=15

    nazwa_funkcji({
      "created_at": "2008-01-05 09:13:16",
      "published_at": "2008-01-15 12:00:00",
      "modified_at": "2008-01-05 16:10:06",
      "text": "Test & test Pinga na Pinger.pl",
      "mid": "15",
      "cite": "13",
      "user": {
        // autor; tak jak w przypadku [auth_]search_user.js //
      },
      // jeśli jest to wpis na cudzym blogu, dodatkowo:
        "owner": {
          // tak jak w przypadku powyższego elementu 'user' //
        },
      "title": "tytuł wpisu",
      "images": [
        {"title": "smaller.gif", "path": "http://...", "thumb": "http://...", "fid": "101"},
        {"title": "bigfoot.png", "path": "http://...", "thumb": "http://...", "fid": "102"}
      ],
      "files":  [    
        {
            "title": "flame.avi", 
            "path": "http://", 
            "type": "video", 
            "mime": "video/x-msvideo", 
            "size": "289280", 
            "fid": "103"
        }
      ],
      "tags": [
        {"tag": "testy"}, {"tag": "ping"}
      ],
      "maps":[
                "point":"52.281602,20.874023",
                "zoom":"6",
                "desc":"opis mapy"
            ]
      "comments_count": "2"})

auth get user messages by tag

  • funkcjonalność: zwraca wiadomości z podanym tagiem
  • url: http://a.pinger.pl/auth_get_user_messages_by_tag.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • tag - tag (wielowyrazowy tag powinien zawierać znak '+' zamiast spacji)
    • user (opcjonalnie, domyślnie własne wiadomości) - nazwa użytkownika, którego wiadomości chcemy wyświetlić
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/auth_get_user_messages_by_tag.xml/?tag=muzyka&user=ping

    <?xml version="1.0" encoding="UTF-8"?>
    <statuses>
      <status>
        // tak jak w przypadku [auth_]show_message.xml //
      </status>
      <status>
        ...
      </status>
      ...
    </statuses>

    http://a.pinger.pl/auth_get_user_messages_by_tag.js/?callback=nazwa_funkcji&tag=muzyka&user=ping

    nazwa_funkcji([
      {
        // tak jak w przypadku [auth_]show_message.js //
      },
      {
        ...
      },
      ...
    ])

auth search messages by tag

  • funkcjonalność: zwraca wiadomości z podanym tagiem (wyszukiwanie globalne)
  • url: http://a.pinger.pl/auth_search_messages_by_tag.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • tag - tag (wielowyrazowe tagi powinny zawierać znak '+' zamiast spacji)
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/auth_search_messages_by_tag.xml/?tag=muzyka

    <?xml version="1.0" encoding="UTF-8"?>
    <statuses>
      <status>
        // tak jak w przypadku [auth_]show_message.xml //
      </status>
      <status>
        ...
      </status>
      ...
    </statuses>

    http://a.pinger.pl/auth_search_messages_by_tag.js/?callback=nazwa_funkcji&tag=muzyka

    nazwa_funkcji([
      {
        // tak jak w przypadku [auth_]show_message.js //
      },
      {
        ...
      },
      ...
    ])

auth search messages by tags

  • funkcjonalność: zwraca wiadomości oznaczone przynajmniej jednym z podanych tagów (wyszukiwanie globalne)
  • url: http://a.pinger.pl/auth_search_messages_by_tags.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • tag - tags (może być użyte wielokrotnie, patrz przykład)
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/auth_search_messages_by_tag.xml/?tag=muzyka&tag=film

    <?xml version="1.0" encoding="UTF-8"?>
    <statuses>
      <status>
        // tak jak w przypadku [auth_]show_message.xml //
      </status>
      <status>
        ...
      </status>
      ...
    </statuses>

    http://a.pinger.pl/auth_search_messages_by_tag.js/?callback=nazwa_funkcji&tag=muzyka&tag=film

    nazwa_funkcji([
      {
        // tak jak w przypadku [auth_]show_message.js //
      },
      {
        ...
      },
      ...
    ])

auth search messages

  • funkcjonalność: zwraca wiadomości, w których treści lub komentarzach znajduje się podana fraza
  • url: http://a.pinger.pl/api_auth_search_messages.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • text - szukana fraza
    • page (opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/api_auth_search_messages.xml/?tag=muzyka&tag=film

    <?xml version="1.0" encoding="UTF-8"?>
    <statuses>
      <status>
        // tak jak w przypadku [auth_]show_message.xml //
      </status>
      <status>
        ...
      </status>
      ...
    </statuses>

    http://a.pinger.pl/api_auth_search_messages.js/?callback=nazwa_funkcji&text=muzyka

    nazwa_funkcji([
      {
        // tak jak w przypadku [auth_]show_message.js //
      },
      {
        ...
      },
      ...
    ])

auth add message

  • funkcjonalność: dodaje wiadomość
  • url: http://a.pinger.pl/auth_add_message.format
  • metoda: POST
  • formaty: xml, json, js (wymagany paramert callback)
  • parametry:
    • text - treść wiadomości
    • user (opcjonalnie) - login użytkownika, na którego miniblogu można zostawić wiadomość
    • for_friends (opcjonalnie) - jeżeli jest w zapytaniu (dowolna wartość) to wiadomość jest tylko dla znajomych
    • private (opcjonalnie) - jeżeli jest w zapytaniu (dowolna wartość) to wiadomość jest tylko dla właściciela minibloga (ma działanie nadrzędne względem for_friends)
    • access (opcjonalnie) - jeżeli jest w zapytaniu to wartość określa "widoczność" wiadomości (ma działanie nadrzędne względem for_friends oraz private):
      • public - dla wszystkich (domyślnie)
      • protected - tylko dla Twoich znajomych
      • private - tylko dla właściciela minibloga, na którym znajduje się edytowana wiadomość
    • show_at_main (opcjonalnie) - kontrola wyświetlana wpisu na stronie głównej:
      • 0 - nie
      • wartość niezerowa - tak
      • brak parametru lub puste - ustawienie domyślne z profilu użytkownika
    • add_to_my_locs (opcjonalnie) - kontrola dodawania lokalizacji do "Moich miejscówek" (wartości jak dla show_at_main)
    • pub_date (opcjonalnie) - data publikacji wiadomości w formacie "YYYY-MM-DD hh:mm:ss" (oczywiście bez czudzysłowów, skrócony format ISO 8601 ze spacją jako separatorem)
    • file[] (opcjonalnie) - pliki do dodania
    • thumbnail (opcjonalnie) - jeżeli jest w zapytaniu (dowolna wartość) to zdjęcia dołączone do wiadomości będą wyświetlane jako miniaturki
    • tags (opcjonalnie) - kolejne tagi muszą być rodzielone przecinkiem
    • title (opcjonalnie) - tytuł wiadomości
    • cite (opcjonalnie) - id cytowanej wiadomości
    • map_point (opcjonalnie) - współrzędne mpay dołącznej do wiadomości w postaci: 52.281602,20.874023
    • map_zoom (opcjonalnie) - przybliżenie mapy w wiadomości
    • map_desc (opcjonalnie) - opis mapy w wiadomości
    • map_friends_only (opcjonalnie) - określa czy mapa ma być widoczna wyłącznie dla znajomych; wartości: True, False
  • zwrot (format XML):
    <?xml version="1.0" encoding="UTF-8"?>
    <status>
      <created_at>2008-01-05 09:13:16</created_at>
      <published_at>2008-01-15 12:00:00</published_at>
      <modified_at>2008-01-05 16:10:06</modified_at>
      <mid>15</mid>
      <cite>13</cite>
      <text>Test &amp; test Pinga na Pinger.pl</text>
      <title>tytuł wpisu</title>
      <user>
        // autor; tak jak w przypadku [auth_]search_user.xml //
      </user>
      // jeśli jest to wpis na cudzym blogu, dodatkowo:
        <owner>
          // tak jak w przypadku powyższego elementu 'user' //
        </owner>
      <images>
        <image title="smaller.gif" path="http://..." thumb="http://..." fid="101"/>
        <image title="bigfoot.png" path="http://..." thumb="http://..." fid="102"/>
      </images>
      <files>
        <file title="pinger.avi" path="http://..." fid="103"  type="video" mime="video/x-msvideo" size="289280"/>
        <file title="dog.avi" path="http://..." fid="104"  type="video" mime="video/x-msvideo" size="152800"/>
      </files>
      <tags>
        <tag>testy</tag>
        <tag>ping</tag>
      </tags>
      <maps>
    	<map>
    		<point>52.281602,20.874023</point>
    		<zoom>6</zoom>
    		<desc>opis mapy</desc>
    	</map>
      </maps>
      <comments_count>2</comments_count>
    </status>
  • zwrot (format JS):
    nazwa_funkcji({
      "created_at": "2008-01-05 09:13:16",
      "published_at": "2008-01-15 12:00:00",
      "modified_at": "2008-01-05 16:10:06",
      "text": "Test & test Pinga na Pinger.pl",
      "mid": "15",
      "cite": "13",
      "user": {
        // autor; tak jak w przypadku [auth_]search_user.js //
      },
      // jeśli jest to wpis na cudzym blogu, dodatkowo:
        "owner": {
          // tak jak w przypadku powyższego elementu 'user' //
        },
      "title": "tytuł wpisu",
      "images": [
        {"title": "smaller.gif", "path": "http://...", "thumb": "http://...", "fid": "101"},
        {"title": "bigfoot.png", "path": "http://...", "thumb": "http://...", "fid": "102"}
      ],
      "files":  [    
        {
            "title": "flame.avi", 
            "path": "http://", 
            "type": "video", 
            "mime": "video/x-msvideo", 
            "size": "289280", 
            "fid": "103"
        }
      ],
      "tags": [
        {"tag": "testy"}, {"tag": "ping"}
      ],
      "maps":[
                "point":"52.281602,20.874023",
                "zoom":"6",
                "desc":"opis mapy"
            ]
      "comments_count": "2"})

auth change message

  • funkcjonalność: edytuje wiadomość
  • url: http://a.pinger.pl/auth_change_message.format
  • metoda: POST
  • formaty: xml, json, js (wymagany paramert callback)
  • parametry:
    • mid - identyfikator wiadomości
    • text - treść wiadomości
    • access (opcjonalnie) - jeżeli jest w zapytaniu to wartość określa "widoczność" wiadomości:
      • public - dla wszystkich (domyślnie)
      • protected - tylko dla Twoich znajomych
      • private - tylko dla właściciela minibloga, na którym znajduje się edytowana wiadomość
    • show_at_main (opcjonalnie) - jeżeli jest w zapytaniu (dowolna wartość) to wiadomość jest wyświetlana na stronie głównej
    • add_to_my_locs (opcjonalnie) - kontrola dodawania lokalizacji do "Moich miejscówek" (wartości jak dla show_at_main)
    • np (opcjonalnie) - o wartości równej 1 (jeden) jeśli edytowana wiadomości jest jeszcze nieopublikowana
    • pub_date - data publikacji wiadomości w formacie "YYYY-MM-DD hh:mm:ss" (oczywiście bez czudzysłowów, skrócony format ISO 8601 ze spacją jako separatorem), TYLKO dla parametru 'np=1'
    • file[] (opcjonalnie) - pliki do dodania
    • thumbnail (opcjonalnie) - jeżeli jest w zapytaniu (dowolna wartość) to zdjęcia dołączone do wiadomości będą wyświetlane jako miniaturki
    • removed_files[] (opcjonalnie) - id plików do usunięcia
    • tags (opcjonalnie) - kolejne tagi muszą być rodzielone przecinkiem
    • title (opcjonalnie) - tytuł wiadomości
    • cite (opcjonalnie) - id cytowanej wiadomości
    • map_point (opcjonalnie) - współrzędne mpay dołącznej do wiadomości w postaci: 52.281602,20.874023
    • map_zoom (opcjonalnie) - przybliżenie mapy w wiadomości
    • map_desc (opcjonalnie) - opis mapy w wiadomości
    • map_friends_only (opcjonalnie) - określa czy mapa ma być widoczna wyłącznie dla znajomych; wartości: True, False
  • zwrot (format XML):
    <?xml version="1.0" encoding="UTF-8"?>
    <status>
      <created_at>2008-01-05 09:13:16</created_at>
      <published_at>2008-01-15 12:00:00</published_at>
      <modified_at>2008-01-05 16:10:06</modified_at>
      <mid>15</mid>
      <cite>13</cite>
      <text>Test &amp; test Pinga na Pinger.pl</text>
      <title>tytuł wpisu</title>
      <user>
        // autor; tak jak w przypadku [auth_]search_user.xml //
      </user>
      // jeśli jest to wpis na cudzym blogu, dodatkowo:
        <owner>
          // tak jak w przypadku powyższego elementu 'user' //
        </owner>
      <images>
        <image title="smaller.gif" path="http://..." thumb="http://..." fid="101"/>
        <image title="bigfoot.png" path="http://..." thumb="http://..." fid="102"/>
      </images>
      <files>
        <file title="pinger.avi" path="http://..." fid="103"  type="video" mime="video/x-msvideo" size="289280"/>
        <file title="dog.avi" path="http://..." fid="104"  type="video" mime="video/x-msvideo" size="152800"/>
      </files>
      <tags>
        <tag>testy</tag>
        <tag>ping</tag>
      </tags>
      <maps>
    	<map>
    		<point>52.281602,20.874023</point>
    		<zoom>6</zoom>
    		<desc>opis mapy</desc>
    	</map>
      </maps>
      <comments_count>2</comments_count>
    </status>
  • zwrot (format JS):
    nazwa_funkcji({
      "created_at": "2008-01-05 09:13:16",
      "published_at": "2008-01-15 12:00:00",
      "modified_at": "2008-01-05 16:10:06",
      "text": "Test & test Pinga na Pinger.pl",
      "mid": "15",
      "cite": "13",
      "user": {
        // autor; tak jak w przypadku [auth_]search_user.js //
      },
      // jeśli jest to wpis na cudzym blogu, dodatkowo:
        "owner": {
          // tak jak w przypadku powyższego elementu 'user' //
        },
      "title": "tytuł wpisu",
      "images": [
        {"title": "smaller.gif", "path": "http://...", "thumb": "http://...", "fid": "101"},
        {"title": "bigfoot.png", "path": "http://...", "thumb": "http://...", "fid": "102"}
      ],
      "files":  [    
        {
            "title": "flame.avi", 
            "path": "http://", 
            "type": "video", 
            "mime": "video/x-msvideo", 
            "size": "289280", 
            "fid": "103"
        }
      ],
      "tags": [
        {"tag": "testy"}, {"tag": "ping"}
      ],
      "maps":[
                "point":"52.281602,20.874023",
                "zoom":"6",
                "desc":"opis mapy"
            ]
      "comments_count": "2"})

auth remove message

  • funkcjonalność: usuwa wiadomość o podanym mid
  • url: http://a.pinger.pl/auth_remove_message.format
  • metoda: GET
  • formaty: xml, json, js (wymagany paramert callback)
  • parametry:
    • mid - identyfikator wiadomości
  • przykłady:

    http://a.pinger.pl/auth_remove_message.xml/?mid=15

    <?xml version="1.0" encoding="UTF-8"?>
    <confirm mid="15" />

    http://a.pinger.pl/auth_remove_message.js/?callback=nazwa_funkcji&mid=15

    nazwa_funkcji({"mid": 15})

auth get comments

  • funkcjonalność: zwraca komentarze do podanej wiadomości
  • url: http://a.pinger.pl/auth_get_comments.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany parametr callback)
  • parametry:
    • mid - identyfikator wiadomości
  • przykłady:

    http://a.pinger.pl/auth_get_comments.xml/?mid=15

    <?xml version="1.0" encoding="UTF-8"?>
    <statuses>
      <status>
      <created_at>2008-01-05 09:13:16</created_at>
      <cid>123</cid>
      <text>Test komentarza</text>
      <user>
        // jeśli autor był zarejestrowany: tak jak w przypadku [auth_]search_user.xml //
        // jeśli autor był niezarejestrowany:
            <login>_</login>
            <nickname>gość z sieci ;)</nickname>
            <profile_image_url>http://.../default.gif</profile_image_url>
            <profile_image_url_thumb>http://.../default_thumb.gif</profile_image_url_thumb>
      </user>
    </status>
      <status>
        ...
      </status>
      ...
    </statuses>

    http://a.pinger.pl/auth_get_comments.js/?callback=nazwa_funkcji&mid=15

    nazwa_funkcji([
      {
      "created_at": "2008-01-05 09:13:16",
      "text": "Test komentarza",
      "cid": 123,
      "user": {
        // jeśli autor był zarejestrowany: tak jak w przypadku [auth_]search_user.js //
        // jeśli autor był niezarejestrowany:
            "login": "_",
            "nickname": "gość z sieci ;)",
            "profile_image_url": "http://.../default.gif",
            "profile_image_url_thumb": "http://.../default_thumb.gif",
      },
    },
      {
        ...
      },
      ...
    ])

auth get last comments

  • funkcjonalność: zwraca 10 ostatnich komentarzy dodanych do wpisow na blogu użytkownika 'user'
  • url: http://a.pinger.pl/auth_get_last_comments.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • parametry:
    • user - login właściciela bloga
  • przykłady:

    http://a.pinger.pl/api_auth_get_last_comments.xml/?user=ping

    http://a.pinger.pl/api_auth_get_last_comments.js/?callback=nazwa_funkcji&user=ping

auth get last discussion comments

  • funkcjonalność: zwraca do 10 ostatnich komentarzy z dyskusji prowadzonych przez autoryzowanego użytkownika (nie są zwracane komentarze samego użytkownika)
  • url: http://a.pinger.pl/auth_get_last_discussion_comments.format
  • metoda: GET
  • formaty: xml, rss, atom, json, js (wymagany paramert callback)
  • przykłady:

    http://a.pinger.pl/auth_get_last_discussion_comments.xml

    http://a.pinger.pl/auth_get_last_discussion_comments.rss

auth add comment

  • funkcjonalność: dodaje komentarz do wiadomości
  • url: http://a.pinger.pl/auth_add_comment.format
  • metoda: POST
  • formaty: xml, json, js (wymagany paramert callback)
  • parametry:
    • mid - identyfikator wiadomości
    • text - treść komentarza (maksymalnie 1000 znaków)
  • zwrot (format XML):
    <?xml version="1.0" encoding="UTF-8"?>
    <status>
      <created_at>2008-01-05 09:13:16</created_at>
      <cid>123</cid>
      <text>Test komentarza</text>
      <user>
        // jeśli autor był zarejestrowany: tak jak w przypadku [auth_]search_user.xml //
        // jeśli autor był niezarejestrowany:
            <login>_</login>
            <nickname>gość z sieci ;)</nickname>
            <profile_image_url>http://.../default.gif</profile_image_url>
            <profile_image_url_thumb>http://.../default_thumb.gif</profile_image_url_thumb>
      </user>
    </status>
  • zwrot (format JS):
    nazwa_funkcji({
      "created_at": "2008-01-05 09:13:16",
      "text": "Test komentarza",
      "cid": 123,
      "user": {
        // jeśli autor był zarejestrowany: tak jak w przypadku [auth_]search_user.js //
        // jeśli autor był niezarejestrowany:
            "login": "_",
            "nickname": "gość z sieci ;)",
            "profile_image_url": "http://.../default.gif",
            "profile_image_url_thumb": "http://.../default_thumb.gif",
      },
    })

auth remove comment

  • funkcjonalność: usuwa komentarz
  • url: http://a.pinger.pl/auth_remove_comment.format
  • metoda: GET
  • formaty: xml, json, js (wymagany paramert callback)
  • parametry:
    • cid - identyfikator komentarza
  • przykłady:

    http://a.pinger.pl/auth_remove_comment.xml/?cid=123

    <?xml version="1.0" encoding="UTF-8"?>
    <confirm cid="123" />

    http://a.pinger.pl/auth_remove_comment.js/?callback=nazwa_funkcji&cid=123

    nazwa_funkcji({"cid": 123})

auth get friends list

  • funkcjonalność: zwraca listę znajomych danego użytkownika
  • url: http://a.pinger.pl/auth_get_friends_list.format
  • metoda: GET
  • formaty: xml, json, js (wymagany parametr callback)
  • parametry:
    • user (domyślnie własna) - nazwa użytkownika, którego znajomych chcemy wyświetlić
  • przykłady:

    http://a.pinger.pl/auth_get_friends_list.xml/?user=ping

    <?xml version="1.0" encoding="UTF-8"?>
    <friends>
      <user>
        // tak jak w przypadku [auth_]search_user.xml //
      </user>
      <user>
        ...
      </user>
      ...
    </friends>

    http://a.pinger.pl/auth_get_friends_list.js/?callback=nazwa_funkcji&user=ping

    nazwa_funkcji([
      {
        // tak jak w przypadku [auth_]search_user.js //
      },
      {
        ...
      },
      ...
    ])

auth add friend

  • funkcjonalność: dodaje znajomego
  • url: http://a.pinger.pl/auth_add_friend.format
  • metoda: GET
  • formaty: xml, json, js (wymagany parametr callback)
  • parametry:
    • user - login nowego znajomego
  • przykłady:

    http://a.pinger.pl/auth_add_friend.xml/?user=ping

    <?xml version="1.0" encoding="UTF-8"?>
    <confirm login="ping" />

    http://a.pinger.pl/auth_add_friend.js/?callback=nazwa_funkcji&user=ping

    nazwa_funkcji({"login": "ping"})

auth remove friend

  • funkcjonalność: usuwa znajomego
  • url: http://a.pinger.pl/auth_remove_friend.format
  • metoda: GET
  • formaty: xml, json, js (wymagany parametr callback)
  • parametry:
    • user - login znajomego
  • przykłady:

    http://a.pinger.pl/auth_remove_friend.xml/?user=ping

    <?xml version="1.0" encoding="UTF-8"?>
    <confirm login="ping" />

    http://a.pinger.pl/auth_remove_friend.js/?callback=nazwa_funkcji&user=ping

    nazwa_funkcji({"login": "ping"})

auth search user

  • funkcjonalność: zwraca 25 użytkowników, których login, pseudonim lub miasto pasują do szukanego wzorca
  • url: http://a.pinger.pl/auth_search_user.format
  • metoda: GET
  • formaty: xml, json, js (wymagany parametr callback)
  • parametry:
    • user - szukana fraza: login, psudonim, miasto
    • page(opcjonalnie, domyślnie 1) - numer strony
  • przykłady:

    http://a.pinger.pl/auth_search_user.xml/?user=ping

    <?xml version="1.0" encoding="UTF-8"?>
    <users>
      
      <user>
        <login>ping</login>
        <nickname>Pinger admin ;)</nickname>
        <country>Polska</country>
        <location>Białystok</location>
        <description>Tak, to moja strona</description>
        <motto>Seize the day... :P</motto>
        <phone>+48...</phone>
        <gg>16</gg>
        <tlen>pinger</tlen>
        <skype>skyped_pinger</skype>
        <email>ping@o2.pl</email>
        <profile_image_url>http://...</profile_image_url>
        <profile_image_url_thumb>http://...</profile_image_url_thumb>
        <user_pages>
            <page>
                <www>http://...</www>
                <desc>moja strona</desc>
            </page>
            ...
        </user_pages>
        <categories>
            <category cat="music">Muzyka</category>
            ...
        </categories>
        <url>http://ping.pinger.pl/</url>
      </user>
    
      <user>
        ...
      </user>
      ...
    </users>

    http://a.pinger.pl/auth_search_user.js/?callback=nazwa_funkcji&user=ping

    nazwa_funkcji([
      {
        "login": "ping",
        "nickname": "Pinger admin ;)",
        "country": "Polska",
        "description": "Tak, to moja strona",
        "location": "Białystok",
        "motto": "Seize the day... :P",
        "phone": "+48...",
        "gg": "16",
        "tlen": "pinger",
        "skype": "skyped_pinger",
        "email": "ping@o2.pl",
        "profile_image_url": "http://...",
        "profile_image_url_thumb": "http://...",
        "user_pages": [
            {"www": "http://...", "desc": "moja strona"},
            ...
        ],
        "categories": [    
            {"cat": "music", "desc": "Muzyka"},
            ...
        ],
        "url": "http://ping.pinger.pl/"
      },
      {
        ...
      },
      ...
    ])