Wykop API wersja 1.0 Ograniczenia: Ta dokumentacja dotyczy wersji tylko do odczytu Wykop API 1
Spis treści Wstęp...4 Klucz aplikacji...5 Uprawnienia...6 Komunikacja...7 Przekazywanie parametrów...7 Ustawianie formatu odpowiedzi...8 Filtrowanie odpowiedzi...8 Zasoby...9 Link...9 Index...9 Comments...9 Reports...9 Digs...10 Related...10 Buryreasons...11 Links...11 Promoted...11 Upcoming...11 Popular...12 Promoted...12 Upcoming...12 Profile...13 Index...13 Added...13 Groups...13 Published...14 Commented...14 Digged...15 Search...15 Index...15 Groups...15 Index...15 Top...16 Index...16 Date...16 Entries...16 Index...16 Rank...17 Index...17 Observatory...17 Votes...17 Comments...18 Entries...18 Formaty odpowiedzi...19 Profile...19 2
Comment...20 Bury...20 Dig...20 Link...21 Group...22 Relatedlink...22 Mywykop...22 Entry...23 Entrycomment...23 Notification...24 Vote...24 Stałe...25 Grupa użytkownika...25 Kody błędów...25 Przykłady...27 Wywołanie API...27 Pobranie listy linków...27 Dodanie komentarza...28 3
Wstęp Wykop API jest usługą udostępniającą zasoby i logikę serwisu wykop.pl bez pośrednictwa warstwy interfejsu. Usługa skierowana jest do programistów zainteresowanych budowaniem własnych rozwiązań korzystających z danych i mechanizmów publicznie dostępnych w serwisie. Wykop API to usługa sieciowa opierająca swoje działanie na protokole HTML. Odpowiedzi zwracane przez serwis dostępne są w formatach JSON (http://www.json.org/) oraz XML (http://www.w3.org/xml/). Komunikacja z API odbywa się w oparciu o architekturę REST. Każdy obiekt dostępny w serwisie reprezentowany jest przez odpowiedni zasób API. Każdy z zasobów ma specyficzny zestaw metod, które można na nim wykonać. Za pomocą Wykop API możesz m.in.: przeglądać listę znalezisk ze strony głównej i wykopaliska przeglądać szczegóły znaleziska, komentarze do niego, listę osób głosujących przeglądać profile użytkowników serwisu przeglądać wpisy z serwisu mikroblogowego Szczegóły dostępu do poszczególnych zasobów przedstawione zostały w dalszej części niniejszej dokumentacji. 4
Klucz aplikacji Każda aplikacja wymaga unikatowego klucza aplikacji. Klucz nadawany jest raz, podczas rejestracji aplikacji i nie może być wykorzystywany z innym aplikacjami niż ta, do której został przypisany. Klucz aplikacji musi być wykorzystywany do autoryzacji każdego żądania skierowanego do Wykop API. Nie przekazanie klucza w żądaniu, przekazanie klucza niepoprawnego lub unieważnionego spowoduje zwrócenie odpowiedniego komunikatu błędu oraz uniemożliwi korzystanie z zasobów Wykop API. 5
Uprawnienia Aplikacja może mieć jeden z dwóch poziomów uprawnień: aplikacja tylko do odczytu dostęp tylko do tych funkcjonalności, które w żaden sposób nie modyfikują danych w Wykop.pl aplikacja z pełnymi prawami dostęp do wszystkich funkcjonalności serwisu rejestracja tego typu aplikacji jest na obecnym etapie zablokowana Metody wymagające pełnego dostępu są oznaczone w tej dokumentacji w odpowiedni sposób. Dodatkowo na aplikację mogą być nałożone dobowe limity ilości wykonanych żądań. Aplikacja może mieć również nałożone ograniczenia co do sposobu logowania użytkownika. W przypadku nałożenia takiego ograniczenia wymagane jest połączenie przez użytkownika swojego konta z aplikacją w serwisie Wykop.pl i wprowadzenie przez użytkownika swojego klucza do aplikacji. 6
Komunikacja Komunikacja z Wykop API odbywa się w architekturze REST. W celu wykonania polecenia Wykop API należy wywołać odpowiednio skonstruowany adres URI. API dostępne jest pod adresem: http://a.wykop.pl/ Każde żądanie składa się z 3 elementów: rodzaj zasobu metoda zasobu parametry Przykładowe żądanie: http:/a.wykop.pl/link/index/54321/appkey,12345 gdzie: http://a.wykop.pl/ - domena serwera API link typ zasobu index metoda zasobu index 54321/appkey,12345 lista parametrów: 54321 identyfikator linku 12345 wartość parametru appkey Przekazywanie parametrów W Wykop API istnieją trzy rodzaje parametrów: kolejne parametry rozdzielone są znakiem slash (/). Są to parametry precyzujące jaki fragment danego zasobu ma zostać wybrany, np. identyfikator linka lub nazwa użytkownika. Kolejne parametry rozdzielane są znakiem slash. 7
są to parametry związane z autoryzacją lub parametryzacją żądania. Parametry przekazuje się w parach nazwa,wartość, np. appkey,12345,userkey,54321 spowoduje przekazania parametrów appkey o wartości 12345 oraz userkey o wartości 54321. parametry przekazywane jako metoda POST protokołu HTTP Ustawianie formatu odpowiedzi Wykop API pozwala na odbieranie danych w dwóch formatach: JSON oraz XML. Domyślnym formatem jest JSON. Żeby zmienić go na XML należy dodać parametr format o wartości xml. Na przykład: http://a.wykop.pl/link/54321/appkey,12345,format,xml Filtrowanie odpowiedzi API pozwala na automatyczne odfiltrowanie zwracanych danych. W przypadku, gdy aplikacja docelowa nie potrafi obsłużyć pól zawierających kod HTML należy użyć parametru API output o wartości clear. Na przykład: http://a.wykop.pl/link/54321/appkey,12345,output,clear Spowoduje, że wszystkie pola odpowiedzi zostaną wyczyszczone z kodu HTML. 8
Zasoby Poniżej opisane zostały wszystkie zasoby dostępne w Wykop API oraz metody dostępu do nich. Parametry oznaczone pogrubieniem są wymagane w danym żądaniu. Parametry param1, param2 i kolejne oznaczają kolejne. Metody wymagające prawa do zapisu zostały oznaczone przez Metoda wymaga praw do zapisu. Link Index Pobranie informacji o linku param1 identyfikator linka userkey klucz użytkownika Tablica zawierająca dane o linku format danych link Comments Pobranie listy komentarzy do linku param1 identyfikator linka tablica zawierająca listę komentarzy format danych comment Reports Pobranie zakopów 9
param1 identyfikator linka tablica zawierająca listę zakopów format danych bury Digs Pobranie wykopów param1 identyfikator linka tablica zawierająca listę wykopów format danych dig Related Pobranie linków powiązanych param1 identyfikator linka userkey klucz użytkownika tablica zawierająca listę powiązanych linków format danych relatedlink 10
Buryreasons Pobranie powodów zakopów. Metoda ta powinna być wykonana raz, na początku działania aplikacji (lub przed pierwszym zakopem) a jej wynik powinien zostać zapisany w aplikacji, tak, żeby niepotrzebnie nie pobierać tych danych za każdym razem. param1 identyfikator linka w którym jest komentarz tablica zawierająca listę powodów zakopów Links Promoted Pobranie linków wykopanych na stronę główną wykop.pl lub stronę główną wybranej grupy group identyfikator grupy page strona sort day (ostatnie 24 godz), week (ostatnie 7 dni), month (ostatnie 30 dni) tablica zawierająca listę linków format danych link Upcoming Pobranie strony wykopaliska wykop.pl lub wybranej grupy 11
group identyfikator grupy page strona sort date (najnowsze), votes (wykopywane), comments (komentowane) tablica zawierająca listę linków format danych link Popular Promoted Pobranie linków ostatnio popularnych na stronie głównej tablica zawierająca listę linków format danych link Upcoming Pobranie linków ostatnio popularnych w wykopalisku 12
tablica zawierająca listę linków format danych link Profile Index Pobranie informacji o użytkowniku param1 nazwa użytkownika tablica zawierająca dane o użytkowniku format danych profile Added Pobranie linków dodanych przez użytkownika param1 nazwa użytkownika page strona tablica zawierająca listę linków format danych link Groups Pobranie listy grup których członkiem jest użytkownik param1 nazwa użytkownika 13
page strona tablica zawierająca listę grup format danych groups Published Pobranie linków opublikowanych przez użytkownika param1 nazwa użytkownika page strona tablica zawierająca listę linków format danych link Commented Pobranie linków skomentowanych przez użytkownika param1 nazwa użytkownika page strona tablica zawierająca listę linków format danych link 14
Digged Pobranie linków wykopanych przez użytkownika param1 nazwa użytkownika page strona tablica zawierająca listę linków format danych link Buried Pobranie linków zakopanych przez użytkownika dostępne tylko dla użytkownika będącego właścicielem konta param1 nazwa użytkownika page strona tablica zawierająca listę linków format danych link Search Index Pobranie wyników wyszukiwania 15
page strona q zapytanie do wyszukiwarki tablica zawierająca listę linków format danych link Groups Index Pobranie informacje o grupach group idektyfikator grupy page numer strony listy grup lista grup format danych group Top Index Pobranie informacji o hitach roku param1 rok w formacie YYYY tablica składająca się z dwunastu tablic linków format danych link 16
Date Pobranie informacje o hitach poszczególnych miesięcy param1 rok w formacie YYYY param2 miesiąc jako liczba od 1 do 12 page - strona tablica linków format danych link Entries Index Pobranie pojedynczego wpisu param1 identyfikator wpisu tablica wpisów format danych entry Rank Index Pobranie rankingu użytkowników page - strona 17
tablica użytkowników format danych profile Observatory Votes Pobranie ostatnich 50 głosów na linki tablica głosów typ danych vote Comments Pobranie ostatnich 25 komentarzy tablica komentarzy format danych comment Entries Pobranie ostatnich 25 wpisów z mikroblogu 18
tablica wpisów format danych entry 19
Formaty odpowiedzi Odpowiedzi podzielone zostały na kilka typów. Profile Pole Wartość Typ login login użytkownika string email zakodowany adres email rejestracji konta string public_email publiczny adres email string name imię i nazwisko string www strona domowa uri jabber komunikator jabber string gg numer gadu gadu int city miasto string about pole o użytkowniku string author_group grupa użytkownika int links_added ilość linków dodanych int links_published ilość linków opublikowanych int comments ilość komentarzy int rank pozycja w rankingu int followers ilość użytkowników obserwujących int following ilość użytkowników obserwowanych int entries ilość wpisów int diggs ilość linków wykopanych int buries ilość linków zakopanych int groups ilość grup których użytkownik jest członkiem int avatar avatar uri 20
avatar_lo avatar (mały rozmiar) uri avatar_med avatar (średni rozmiar) uri avatar_big avatar (duży rozmiar) uri is_observed czy aktualny użytkownik obserwuje tego użytkownika bool Comment Pole Wartość Typ id identyfikator komentarza int date data komentarza date author autor komentarza string author_avatar avatar autora uri author_avatar_med avatar autora (średni rozmiar) uri author_avatar_lo avatar autora (mały rozmiar) uri author_group grupa autora int vote_count liczba głosów int body treść string parent_id identyfikator komentarza nadrzędnego int status Status komentarza (own/new/readed) string Bury Pole Wartość Typ reason identyfikator powodu zakopu int author autor string author_avatar avatar autora uri author_avatar_med avatar autora (średni rozmiar) uri author_avatar_lo avatar autora (mały rozmiar) uri author_group grupa autora int Dig Pole Wartość Typ author autor string 21
author_avatar avatar autora uri author_avatar_med avatar autora (średni rozmiar) uri author_avatar_lo avatar autora (mały rozmiar) uri author_group grupa autora int Link Pole Wartość Typ id identyfikator linka int title tytuł linka string description opis string tags tagi string url adres url w serwisie wykop.pl uri source_url adres źródłowy uri vote_count liczba głosów int comment_count liczba komentarzy int report_count liczba zakopów int date data dodania date author login dodającego string group grupa int author_avatar avatar autora uri author_avatar_med avatar autora (średni rozmiar) uri author_avatar_lo avatar autora (mały rozmiar) uri author_group grupa autora int preview miniatura uri plus18 link dla dorosłych bool status can_vote czy uzytkownik może głosować bool has_own_content czy link ma treść bool Poniżesz pola zostaną wypełnione jeśli do pytania o link lub listę linków zostanie 22
dołożony userkey user_vote dig jeśli użytkownik wykopał ten link, lub bury, jeśli zakopał string user_observe true, jeśli użytkownik obserwuje ten link bool user_favorite true, jeśli użytkownik dodał link do ulubionych bool Group Pole Wartość Typ id identyfikator grupy int link adres URL grupy uri name nazwa grupy string description opis grupy string logo logo uri member_count ilość członków int is_member czy aktualny użytkownik jest członkiem grupy bool Relatedlink Pole Wartość Typ id identyfikator linku int url adres URL linku uri title tytuł linku string vote_count ilość głosów int entry_count ilość wejść z linka (dla linków trackback) int user_vote głos zalogowanego użytkownika (+1 / -1 / null jeśli brak głosu) int Mywykop Wpisy z mojego wykopu dzielą się na dwa rodzaje Pole Wartość Typ type link string 23
Wpis link link comments Tablica komentarzy comment commented Czy obserwowani dodali komentarze bool Pole Wartość Typ type entry string Wpis Entry Pole Wartość Typ id Identyfikator wpisu int entry author Autor wpisu string author_avatar Avatar autora uri author_avatar_med Avatar autora (średni rozmiar) uri author_avatar_lo Avatar autora (mały rozmiar) uri author_group Grupa autora uri date Data dodania wpisu date body Treść wpisu string url Adres wpisu uri receiver Odbiorca string receiver_avatar Avatar odbiorcy uri receiver_avatar_med Avatar odbiorcy (średni rozmiar) uri receiver_avatar_lo Avatar odbiorcy (mały rozmiar) uri receiver_group Grupa odbiorcy int comments Tablica komentarzy do wpisu entrycom ment Entrycomment Pole Wartość Typ id Identyfikator komentarza int author Autor komentarza string author_avatar Avatar autora uri author_avatar_med Avatar autora (średni rozmiar) uri author_avatar_lo Avatar autora (mały rozmiar) uri 24
author_group Grupa autora int date Data dodania komentarza date body Treść komentarza string Notification Pole Wartość Typ author Autor komentarza string author_avatar Avatar autora uri author_avatar_med Avatar autora (średni rozmiar) uri author_avatar_lo Avatar autora (mały rozmiar) uri author_group Grupa autora int date Data dodania powiadomienia date body Treść powiadomienia string type Typ powiadomienia string entry Informacja o wpisie array link Informacja o linku link group Informacja o grupie group comment Informacja o komentarzu array new Czy przeczytane bool Vote Pole Wartość Typ link_id Identyfikator linka int type Typ głosy, dig lub bury string date Data akcji date 25
Stałe Grupa użytkownika Wartość Znaczenie Kod koloru (hex) 0 zielony #339933 1 pomarańczowy #FF5917 2 bordowy #BB0000 4 zbanowany #999999 5 administracja #000000 Kody błędów Kod Komunikat Znaczenie 1 Invalid API key Niepoprawny klucz aplikacji 2 Invalid POST params, Invalid params Niepoprawne parametry przekazane do żądania 3 Not enough params Brak jednego lub więcej z wymaganych parametrów 4 This application does not have permission to write Aplikacja bez prawa do zapisu próbuje wywołać niedozwoloną metodę 11 Invalid user key Niepoprawny klucz użytkownika 12 Wrong user session key Pusty klucz użytkownika 13 User not found, User doesn't exist Nie znaleziono takiego użytkownika, możliwe przedawnienie ważności jego klucza 14 Invalid login or password Niepoprawny login lub hasło 15 Login or password not found in query Brak wymaganego pola login lub hasło 21 Invalid group name Niepoprawna nazwa grupy 22 User must to be a member Użytkownik nie jest członkiem grupy na której wykonywana jest operacja 31 User cannot vote their comments Użytkownik nie może głosować na własne komentarze 32 Invalid link ID Niepoprawny identyfikator linku 33 You cann't observe themeself Użytkownik nie może obserwować samego siebie 41 Link is removed Próba dostępu do usuniętego linku 42 This is private link Próba dostępu do linku z grupy prywatnej, bez bycia członkiem tej grupy 26
1001 API is down, please be patient Przerwa serwisowa 1002 No index method defined Brak zdefiniowanego zasobu w żądaniu 27
Przykłady Poniżej przedstawione zostały przykłady użycia Wykop API w aplikacji napisanej w języku PHP. Wywołanie API function dorequest($url, $post = null) { $options = array( CURLOPT_RETURNTRANSFER => true, CURLOPT_HEADER => false, CURLOPT_ENCODING => "", CURLOPT_USERAGENT => 'WykopWebAgent', CURLOPT_AUTOREFERER => true, CURLOPT_CONNECTTIMEOUT => 15, CURLOPT_TIMEOUT => 15, CURLOPT_MAXREDIRS => 10, ); if ($post!== null) { $post_value = is_array($post)? http_build_query($post, 'f_', '&') : ''; $options[curlopt_post] = 1; $options[curlopt_postfields] = $post_value; } $curl = curl_init($url); curl_setopt_array($curl, $options); $content = curl_exec($curl); $result = curl_getinfo($curl); $result['errno'] = curl_errno($curl); $result['errmsg'] = curl_error($curl); $result['content'] = $content; curl_close($curl); } return $result; Powyższa metoda jest przykładem wykonania połączenia do WykopAPI z wykorzystaniem biblioteki curl. Pobranie listy linków $apiresult = dorequest('http://a.wykop.pl/links/promoted/appkey,yourapikey'); if (!empty($apiresult['content'])) 28
{ } $answer = json_decode($apiresult['content'], true); if (empty($answer['error'])) { foreach ($answer as $link) { echo '['. $link['vote_count']. '] '. $link['title']. '<br />'; } } else { Die('Wystąpił błąd API : '. $answer['error']['message']); } Powyższy kod spowoduje pobranie listy linków ze strony głównej i wyświetlenie tytułów wraz z ilością oddanych na nie głosów. Dodanie komentarza $apiresult = dorequest('http://a.wykop.pl/user/login/appkey,yourapikey', array('accountkey' => 'useraccountkey')); $answer = json_decode($apiresult['content'], true); if (empty($answer['error'])) { if (!empty($answer['userkey'])) { $apiresult = dorequest( 'http://a.wykop.pl/comments/add/12345/appkey,yourapikey,userkey,'. $answer['userkey'], array('body' => 'komentarz dodany przez API')); } } else { Die('Wystąpił błąd API : '. $answer['error']['message']); } Powyższy kod spowoduje dodanie komentarza komentarz dodany przez API do wybranego linku przez użytkownika z kluczem useraccountkey. 29