pinger.pl - dokumentacja API pinger.pl - dla kreatywnych ludzi z wizją!

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/"
  },
  {
    ...
  },
  ...
])

Interfejs komunikacji z serwisem

Założenia

Autoryzacja

Zasoby RESTful

Parametry

Zapytania HTTP

Kody HTTP

Metody

Format metod

Metody użytkowników anonimowych

authorize

public timeline

friends' timeline

user's timeline

discussion timeline

observers timeline

show message

get messages by tag

get last comments

add comment

get friends list

search user

get comments

get user messages by tag

search messages by tag

search messages by tags

search messages

Metody użytkowników zarejestrowanych

auth public timeline

auth friends' timeline

auth user's timeline

auth discussion timeline

auth observers timeline

auth show message

auth get user messages by tag

auth search messages by tag

auth search messages by tags

auth search messages

auth add message

auth change message

auth remove message

auth get comments

auth get last comments

auth get last discussion comments

auth add comment

auth remove comment

auth get friends list

auth add friend

auth remove friend

auth search user

Lista funkcji