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 HTTP. 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
  • dodawać komentarze do znalezisk
  • przeglądać profile użytkowników serwisu
  • dodawać nowe znaleziska
  • wykopywać i zakopywać znaleziska
  • korzystać z serwisu mikro blogowego

Szczegóły dostępu do poszczególnych zasobów przedstawione zostały w dalszej części niniejszej dokumentacji.

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.

Klucz użytkownika

Klucz użytkownika to ciąg znaków przekazywany do aplikacji w odpowiedzi na zalogowanie użytkownika w wykop.pl. Wszystkie żądania wymagające od użytkownika bycia zalogowanym muszą być autoryzowane tym kluczem. Klucz użytkownika ma ograniczoną ważność i po 24 godzinach wygasa.

Logowanie przy użyciu loginu i hasła do konta Wykop

Metoda wykorzystująca hasło do konta Wykop.pl jest domyślnie zablokowana dla nowych aplikacji i może być odblokowana tylko na wyraźną i dobrze umotywowaną prośbę autora aplikacji

Żeby uzyskać dostęp do klucza aplikacja musi zażądać zasobu user/login przekazując w parametrach POST:

  • login - login konta w serwisie wykop.pl
  • password - hasło do konta w serwisie wykop.pl

W odpowiedzi wysyłany jest userkey, który należy używać tak długo, dopóki aplikacja nie zgłosi błędu o jego przeterminowaniu (standardowo 24 godziny).

Logowanie przy użyciu loginu i klucza autoryzacyjnego

Żeby uzyskać dostęp do klucza aplikacja musi zażądać zasobu user/login przekazując w parametrach POST:

  • login - login konta w serwisie wykop.pl
  • accountkey - klucz autoryzacyjny do konta w serwisie wykop.pl dla wybranej aplikacji

W odpowiedzi wysyłany jest userkey, który należy używać tak długo, dopóki aplikacja nie zgłosi błędu o jego przeterminowaniu (standardowo 24 godziny).

W celu uzyskania klucza łączącego konto z aplikacją deweloper powinien przejść do zakładki Twoje aplikacje i wygenerować kod łączący aplikację z kontem. W momencie publikacji aplikacji w katalogu dodatków należy podać klucz API w odpowiednim polu formularza by umożliwić użytkownikom łączenie ich konta z aplikacją.

Uprawnienia

Podczas tworzenia aplikacji twórca może zażądać dostępu do jednego lub większej ilości obszarów działalności w serwisie. Prośba o nadanie uprawnień zostanie wyświetlona użytkownikowi w momencie łączenia konta z aplikacją. W tym momencie użytkownik może odmówić przyznania części z uprawnień. Aplikacja powinna prawidłowo reagować w sytuacjach, gdy któreś z uprawnień zostało odebrane. Możliwe są następujące uprawnienia:

  • Logowanie (login) - umożliwia zalogowanie się na konto użytkownika
  • Głosowanie (votes) - wykopywanie, zakopywanie, oraz głosowanie na komentarze i linki powiązane
  • Mikroblog (microblog) - rozpoczynanie i uczestniczenie w dyskusjach na mikroblogu
  • Komentarze pod znaleziskami (comments) - udział w dyskusjach pod znaleziskami
  • Dodawanie znalezisk (links) - dodawanie znalezisk i linków powiązanych
  • Zarządzanie profilem, ulubionymi, obserwowanymi (profile) - dostęp do ustawień profilu użytkownika

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:

  • parametry metody – 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”.
  • parametry API – 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 POST – parametry przekazywane jako metoda POST protokołu HTTP

Podpisywanie zapytań

WykopAPI wymaga podpisywania wszystkich zapytań wysyłanych do usługi (istnieją od tego wyjątki, są nimi między innymi zapytania nie modyfikujące treści, ale dobrą zasadą jest podpisywanie każdego żądania kierowanego do API. Żeby podpisać żądanie należy w poprawny sposób ustawić nagłówek HTTP apisign (przykładowa implementacja funkcji podpisującej zamieszczona jest w bibliotece wAPI). Wartość nagłówka powinna być wyliczona w następujący sposób:

md5(SEKRET + URL + WARTOŚCI_PARAMETRÓW_POST)

gdzie

  • sekret - sekret połączony z danym klucem API
  • url - adres pod który wysyłane jest zapytanie
  • wartość parametrów post - połączone znakiem przecinka wartości z tablicy przekazywanej jako parametry POST. Paramtery przed połączeniem muszą być posortowane alfabetycznie po nazwie parametru. Do parametrów POST nie zalicza sie plików przesyłanych w paramterach FILE

przykład:

klucz API: abcdefgh
sekret API: MNOPQRST
adres żądania: http://a.wykop.pl/entries/add/appkey/abcdefgh/userkey/klucz_zalogowanego_użytkownika/
zawartość post:
{
embed: 'http://serwer/plik.jpg',
body: 'przykładowy komentarz',
}

sposób liczenia podpisu:

md5("MNOPQRST" + "http://a.wykop.pl/entries/add/appkey/abcdefgh/userkey/klucz_zalogowanego_użytkownika/" + "przykładowy komentarz,http://serwer/plik.jpg") = c1048ea53bdf3d60383b033c5d97f8c1

Wyliczoną wartość należy ustawić jako nagłówek żądania. Brak wartości, lub niepoprawne jej ustawienie spowoduje błąd [6 => Niepoprawnie podpisane żądanie]

Ustawianie formatu odpowiedzi

Wykop API pozwala na odbieranie danych w trzech formatach: JSON, JSONP 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

Zmiana na JSONP polega na ustawieniu parametru format na wartość jsonp, na przykład:

http://a.wykop.pl/link/54321/appkey,12345,format,jsonp

Domyślnie odpowiedź opakowywana jest w funkcję wykopParser(), żeby zmienić nazwę funkcji należy ustawić parametr padding, na przykład

http://a.wykop.pl/link/54321/appkey,12345,format,jsonp,padding,myParser

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.

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 parametry metody. Metody wymagające przyznanych praw zostały odpowiednio oznaczone. W większości przypadków metody wymagające uprawnień automatycznie wymagają też uprawnienia login co wynika z konieczności przekazania userkey w żądaniu.

Comments

Zasób udostępniający operacje na komentarzach

Add

Metoda wymaga prawa do comments

Dodanie nowego komentarza do linka.

Parametry metody param1 – identyfikator linka dla którego dodawany jest komentarz
param2 – identyfikator komentarza nadrzędnego
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST body – treść komentarza
embed - url do pliku graficznego lub filmu osadzonego w serwisie hostującym Wideo
Parametry FILE embed - plik graficzny który ma być osadzony w obiekcie (parametr nadpisuje url)

Odpowiedź:

id - id nowego komentarza

Plus

Metoda wymaga prawa do votes

Oddanie głosu „+” na komentarz użytkownika

Parametry metody param1 – identyfikator linka dla którego dodawany jest komentarz
param2 – identyfikator komentarza
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

vote – wartość punktów po oddaniu głosu

Minus

Metoda wymaga prawa do votes

Oddanie głosu „-” na komentarz użytkownika

Parametry metody param1 – identyfikator linka dla którego dodawany jest komentarz
param2 – identyfikator komentarza
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

vote – wartość punktów po oddaniu głosu

Edit

Metoda wymaga prawa do comments

Edycja treści komentarza.

Parametry metody param1 – identyfikator komentarza
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST body – treść komentarza

Odpowiedź:

id - id edytowanego komentarza.

Delete

Metoda wymaga prawa do comments

Usuwanie komentarza.

Parametry metody param1 – identyfikator komentarza
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

id - id usuniętego komentarza.

Link

Index

Pobranie informacji o linku

Parametry metody param1 – identyfikator linka
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

Tablica zawierająca dane o linku – format danych Link

Dig

Metoda wymaga prawa do votes

Wykopanie linka

Parametry metody param1 – identyfikator linka
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica o polach

  • success - true w przypadku powodzenia
  • vote – ilość głosów
Cancel

Metoda wymaga prawa do votes

Cofnięcie głosu

Parametry metody param1 – identyfikator linka
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica o polach

  • success - true w przypadku powodzenia
  • vote – ilość głosów
Bury

Metoda wymaga prawa do votes

Zakopanie linka

Parametry metody param1 – identyfikator linka
param2 - identyfikator powodu zakopu
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica o polach

  • success - true w przypadku powodzenia
  • vote – ilość głosów
Comments

Pobranie listy komentarzy do linku

Parametry metody param1 – identyfikator linka
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca listę komentarzy – format danych Comment

Reports

Pobranie zakopów

Parametry metody param1 – identyfikator linka
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca listę zakopów – format danych Bury

Digs

Pobranie wykopów

Parametry metody param1 – identyfikator linka
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca listę wykopów – format danych Dig

Related

Pobranie linków powiązanych

Parametry metody param1 – identyfikator linka
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca listę powiązanych linków – format danych Relatedlink

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.

Parametry metody
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca listę powodów zakopów

Observe

Metoda wymaga prawa do profile

Dodaje i usuwa link z obserwowanych

Parametry metody param1 – identyfikator linka
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true w przypadku powodzenia

Favorite

Metoda wymaga prawa do profile

Dodaje i usuwa link z ulubionych

Parametry metody param1 – identyfikator linka
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true w przypadku powodzenia

Links

Promoted

Pobranie linków wykopanych na stronę główną wykop.pl lub stronę główną wybranej grupy

Parametry metody
Parametry API appkey – klucz aplikacji
page – strona
sort – day (ostatnie 24 godz), week (ostatnie 7 dni), month (ostatnie 30 dni)
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Upcoming

Pobranie strony wykopaliska wykop.pl lub wybranej grupy

Parametry metody
Parametry API appkey – klucz aplikacji
page – strona
sort – date (najnowsze), votes (wykopywane), comments (komentowane)
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Popular

Promoted

Pobranie linków z ramki "Ostatnio Popularne" wyświetlanej na stronie głównej

Parametry metody
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Upcoming

Pobranie linków z ramki "Ostatnio Popularne" wyświetlanej na wykopalisku

Parametry metody
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Profile

Index

Pobranie informacji o użytkowniku

Parametry metody param1 - nazwa użytkownika
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca dane o użytkowniku – format danych Profile

Added

Pobranie linków dodanych przez użytkownika

Parametry metody param1 - nazwa użytkownika
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Published

Pobranie linków opublikowanych przez użytkownika

Parametry metody param1 - nazwa użytkownika
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Commented

Pobranie linków skomentowanych przez użytkownika

Parametry metody param1 - nazwa użytkownika
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Comments

Pobranie komentarzy dodanych przez użytkownika wraz z linkami

Parametry metody param1 - nazwa użytkownika
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę komentarzy – format danych Comment

Digged

Pobranie linków wykopanych przez użytkownika

Parametry metody param1 - nazwa użytkownika
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Buried

Metoda wymaga prawa do profile

Pobranie linków zakopanych przez użytkownika – dostępne tylko dla użytkownika będącego właścicielem konta

Parametry metody param1 - nazwa użytkownika
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Observe

Metoda wymaga prawa do profile

Rozpoczęcie obserwowania użytkownika

Parametry metody param1 - nazwa użytkownika
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true – w przypadku sukcesu

Unobserve

Metoda wymaga prawa do profile

Usunięcie użytkownika z listy obserwowanych

Parametry metody param1 – login użytkownika
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true – w przypadku sukcesu

Block

Metoda wymaga prawa do profile

Dodanie użytkownika do czarnej listy

Parametry metody param1 - nazwa użytkownika
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true – w przypadku sukcesu

Unblock

Metoda wymaga prawa do profile

Usunięcie użytkownika z czarnej listy

Parametry metody param1 – login użytkownika
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true – w przypadku sukcesu

Followers

Pobranie listy obserwowanych przez użytkownika

Parametry metody param1 – login użytkownika
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę profili – format danych Profile

Followed

Pobranie listy obserwujących użytkownika

Parametry metody param1 – login użytkownika
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę profili – format danych Profile

Favorites

Pobranie publicznej listy linków obserwowanych przez użytkownika

Parametry metody param1 - nazwa użytkownika
param2 - id listy
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Entries

Pobranie wpisów z mikrobloga dodanych przez użytkownika

Parametry metody param1 - nazwa użytkownika
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę wpisów – format danych Entry

EntriesComments

Pobranie komentarzy do wpisów dodanych przez użytkownika wraz z wpisami

Parametry metody param1 - nazwa użytkownika
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę komentarzy – format danych EntryComment

Related

Pobranie dodanych linków powiązanych

Parametry metody param1 - nazwa użytkownika
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę komentarzy – format danych RelatedLink

Search

Index

Pobranie wyników wyszukiwania

Parametry metody
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST q – zapytanie do wyszukiwarki

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Links

Wyszukiwanie znalezisk

Parametry metody
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST q – zapytanie do wyszukiwarki
what – rodzaj znalezisk: all (wszystkie), promoted (na głównej), archive (zarchiwizowane), duplicates (duplikaty)
sort – sortowanie: best (najlepsze), diggs (po liczbie wykopów), comments (po liczbie komentarzy), new (po czasie dodania)
when – rodzaj znalezisk: all (wszystkie), today (dzisiaj), yesterday (wczoraj), week (ostatni tydzień), month (ostatni miesiąc), range (zakres czasu)
from - data początkowa (DD/MM/YYYY)
to - data końcowa (DD/MM/YYYY)
votes - minimalna liczba głosów

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Entries

Wyszukiwanie wpisów z mikroblogu

Parametry metody
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST q – zapytanie do wyszukiwarki

Odpowiedź:

tablica zawierająca listę wpisów – format danych Wpis

Profiles

Wyszukiwanie profili

Parametry metody
Parametry API appkey – klucz aplikacji
Parametry POST q – zapytanie do wyszukiwarki

Odpowiedź:

tablica zawierająca listę profili – format danych Profile

User

Login

Metoda wymaga prawa do login

Zalogowanie użytkownika – powoduje wygenerowanie userkey potrzebnego do autoryzowania wszystkich operacji modyfikujących dane.

Do zalogowania użytkownika można użyć jednej z dwóch metod:

  • logowanie z użyciem loginu i hasła. Jako parametr POST należy przekazać login i hasło użytkownika, który ma zostać zalogowany
  • logowanie przez klucz konta – użytkownik loguje się przez klucz wygenerowany na stronie wykop.pl. Każdy użytkownik może wygenerować klucz, który jest unikatowy dla pary użytkownik-aplikacja i przy pomocy tego klucza zalogować się na swoje konto w wykop.pl z poziomu API

Parametry metody
Parametry API appkey – klucz aplikacji
Parametry POST login – login użytkownika
password – hasło użytkownika
lub
accountkey - klucz użytkownika

Odpowiedź:

klucz użytkownika - userkey

Favorites

Pobranie ulubionych linków użytkownika

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica linków – format danych Link

Observed

Pobranie obserwowanych linków użytkownika

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica linków – format danych Link

Tags

Pobranie obserwowanych tagów użytkownika

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica obserwowanych tagów

Connect

Metoda wymaga prawa do login

Połączenie konta użytkownika z aplikacją.

Po wygenerowaniu klucza możliwe będzie przeprowadzenie logowania przez klucz konta. Klucz konta zostanie przekazany w odpowiedzi na poprawnie przeprowadzony proces logowania

Parametry metody
Parametry API appkey – klucz aplikacji
redirect – adres powrotu po prawidłowym wykonaniu logowania zakodowany w następujący sposób (kod w języku PHP):
urlencode(base64_encode($url))
secure – klucz zabezpieczający tworzony przez skrót md5 z połączonych ciągów APPLICATION_SECRET i redirect. Wymagany gdy podany redirect. Podpis tworzymy w następujący sposób (kod w języku PHP):
md5($secret . $url)

Odpowiedź:

w przypadku nie ustawienia zmiennej redirect w odpowiedzi następuje przekierowanie na adres https://www.wykop.pl/user/ConnectSuccess/appkey/APPKEY/login/LOGIN_UZYTKOWNIKA/token/USERKEY_UZYTKOWNIKA/

w przypadku ustawienia zmiennej redirect w odpowiedzi następuje przekierowanie na redirect z dołączonym parametrem connectData. Parametr ten zbudowany jest w następujący sposób (kod w języku PHP):

base64_encode(
	json_encode(
		array(	'appkey' => 'APPKEY', 
			'login' => 'LOGIN_UZYTKOWNIKA', 
			'token' => 'USERKEY_UZYTKOWNIKA'
			'sign'	=> 'PODPIS'
		)
	)
);
Podpis służy do weryfikacji nadawcy komunikatu i tworzony jest w następujący sposób:
md5(APPSECRET + appkey + login + token);

Po odebraniu informacji o loginie i tokenie należy je wykorzystać do wykonania requestu metodą User Login.

Top

Index

Pobranie informacji o hitach roku

Parametry metody param1 - rok w formacie YYYY
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica składająca się z dwunastu tablic linków – format danych Link

Date

Pobranie informacje o hitach poszczególnych miesięcy

Parametry metody param1 - rok w formacie YYYY
param2 - miesiąc jako liczba od 1 do 12
Parametry API appkey – klucz aplikacji
Parametry POST page - strona

Odpowiedź:

tablica linków – format danych Link

Hits

25 losowych znalezisk pojawiających się w ramce "Wybrane Hity" na górze strony (z dużym zdjęciem)

Parametry metody
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica linków – format danych Link

Add

Index

DEPRECATED

Metoda wymaga prawa do links

Dodanie linka do wykopaliska

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
group – nazwa oficjalnego tagu, bez znaku "#"
Parametry POST url – adres strony
title – tytuł, od 6 do 80 znaków
description – opis, od 20 do 300 znaków
tags – tagi rozdzielone spacjami
type – typ linka, „news”, „picture” lub „video”
plus18 – tylko dla dorosłych, 1 lub 0 – domyślnie 0

Odpowiedź:

obiekt link jeśli udało się dodać link - format danych Link - lub tablica z błędami. Możliwe błędy prezentuje poniższa tablica

Pole Komunikat Znaczenie
url Empty url adres pusty
Invalid url niepoprawny adres url
Url is banned domena zablokowana
Url not available adres jest niedostępny
Invalid content type zły typ dodawanej treści
title Empty title pusty tytuł
Title too short or too long [6-80] zła długość tytułu, musi mieć od 6 do 80 znaków
description Empty description pusty opis
Description too short or too long [20-300] zła długość opisu, musi mieć od 20 do 300 znaków
tags Tags empty tagi puste
Invalid tags pole tagi zwiera niepoprawne znaki
Tags too long [60 chars] tagi za długie
type Invalid link type pusty lub niepoprawny typ

Related

Plus

Metoda wymaga prawa do votes

Oddanie głosu „+” na link powiązany

Parametry metody param1 – identyfikator linka w którym jest link powiązany
param2 – identyfikator powiązanego
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

vote – wartość punktów po oddaniu głosu

Minus

Metoda wymaga prawa do votes

Oddanie głosu „-” na link powiązany

Parametry metody param1 – identyfikator linka w którym jest link powiązany
param2 – identyfikator powiązanego
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

vote – wartość punktów po oddaniu głosu

Add

Metoda wymaga prawa do links

Dodawanie nowego linka powiązanego do linka.

Parametry metody param1 – identyfikator linka w którym ma być link powiązany
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST url – adres strony
title – tytuł, od 6 do 80 znaków
plus18 – tylko dla dorosłych, 1 lub 0 – domyślnie 0

Odpowiedź:

id – id dodanego linka powiązanego

Mywykop

Index

Pobranie listy znalezisk i wpisów z „Mojego wykopu” (stworzone przez obserwowanego użytkownika lub zawierające obserwowany tag)

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page - strona
Parametry POST

Odpowiedź:

lista znalezisk i wpisów z „mojego wykopu” – format danych Mywykop

Tags

Pobranie listy znalezisk i wpisów z „Mojego wykopu” (zawierające obserwowany tag)

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page - strona
Parametry POST

Odpowiedź:

lista znalezisk i wpisów z „mojego wykopu” – format danych Mywykop

Users

Pobranie listy znalezisk i wpisów z „Mojego wykopu” (stworzone przez obserwowanego użytkownika)

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page - strona
Parametry POST

Odpowiedź:

lista znalezisk i wpisów z „mojego wykopu” – format danych Mywykop

Observing
DEPRECATED

Pobranie listy wpisów z „Mojego wykopu” ograniczona do użytkowników obserwowanych przez zalogowanego użytkownika

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page - strona
Parametry POST

Odpowiedź:

lista wpisów z „mojego wykopu” – format danych Mywykop

Mine
DEPRECATED

Pobranie listy wpisów zalogowanego użytkownika z „Mojego wykopu”

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page - strona
Parametry POST

Odpowiedź:

lista wpisów z „mojego wykopu” – format danych Mywykop

Received
DEPRECATED

Wiadomości skierowane do użytkownika

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page - strona
Parametry POST

Odpowiedź:

lista wpisów z „mojego wykopu” – format danych Mywykop

Notifications

Pobranie listy powiadomień użytkownika (bez powiadomieniach o tagach)

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page - strona
Parametry POST

Odpowiedź:

lista powiadomień – format danych Notification

NotificationsCount

Pobranie ilości nieprzeczytanych powiadomień (bez powiadomieniach o tagach)

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

count – liczba nieprzeczytanych powiadomień

HashTagsNotifications

Pobranie listy powiadomień użytkownika (tylko powiadomieniach o tagach)

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
page - strona
Parametry POST

Odpowiedź:

lista powiadomień – format danych Notification

HashTagsNotificationsCount

Pobranie ilości nieprzeczytanych powiadomień (tylko powiadomieniach o tagach)

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

count – liczba nieprzeczytanych powiadomień

ReadNotifications

Oznaczenie powiadomień jako przeczytanych

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

pusta

ReadHashTagsNotifications

Oznaczenie powiadomień z tagów jako przeczytanych

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

pusta

MarkAsReadNotification

Oznaczenie pojedynczego powiadomienia z jako przeczytane

Parametry metody param1 – identyfikator powiadomienia
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true

Entries

Index

Pobranie pojedynczego wpisu

Parametry metody param1 – identyfikator wpisu
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

wpis – typ danych Entry

Add

Metoda wymaga prawa do microblog

Dodanie wpisu na mikroblog użytkownika

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST body - treść wpisu
embed - url do pliku graficznego lub filmu osadzonego w serwisie hostującym Wideo
Parametry FILE embed - plik graficzny który ma być osadzony w obiekcie (parametr nadpisuje url)

Odpowiedź:

id - identyfikator wpisu lub false przy niepowodzeniu

Edit

Metoda wymaga prawa do microblog

Edycja treści wpisu.

Parametry metody param1 – identyfikator wpisu
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST body – treść wpisu

Odpowiedź:

id - id edytowanego wpisu.

Delete

Metoda wymaga prawa do microblog

Usuwanie wpisu.

Parametry metody param1 – identyfikator wpisu
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

id - id usuniętego wpisu.

AddComment

Metoda wymaga prawa do microblog

Dodanie wpisu komentarza do wpisu na mikroblogu użytkownika

Parametry metody param1 – identyfikator wpisu
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST body - treść komentarza
embed - url do pliku graficznego lub filmu osadzonego w serwisie hostującym Wideo
Parametry FILE embed - plik graficzny który ma być osadzony w obiekcie (parametr nadpisuje url)

Odpowiedź:

id – identyfikator komentarza lub false przy niepowodzeniu

EditComment

Metoda wymaga prawa do microblog

Edycja treści komentarza do wpisu.

Parametry metody param1 – identyfikator wpisu
param2 – identyfikator komentarza do wpisu
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST body – treść komentarza

Odpowiedź:

id - id edytowanego komentarza.

DeleteComment

Metoda wymaga prawa do microblog

Usuwanie komentarza do wpisu.

Parametry metody param1 – identyfikator wpisu
param2 – identyfikator komentarza do wpisu
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

id - id usuniętego komentarza do wpisu.

Vote

Metoda wymaga prawa do votes

Głosowanie na wpis lub komentarz do wpisu

Parametry metody param1 – typ obiektu (entry/comment)
param2 – identyfikator wpisu
param3 – identyfikator komentarza do wpisu (dla param1 = comment)
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

vote - ilość głosów

voters - lista głosujących

Unvote

Metoda wymaga prawa do votes

Usuwanie głosu na wpis lub komentarz do wpisu

Parametry metody param1 – typ obiektu (entry/comment)
param2 – identyfikator wpisu
param3 – identyfikator komentarza do wpisu (dla param1 = comment)
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

vote - ilość głosów

voters - lista głosujących

Favorite

Metoda wymaga prawa do profile

Dodaje i usuwa wpis z ulubionych

param1 – identyfikator wpisu
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

user_favorite - true, jeśli użytkownik dodał wpis do ulubionych

Rank

Index

Pobranie rankingu użytkowników

Parametry metody order - sposób sortowania wyników, (rank - domyślnie; comment_count, link_count, hp_link_count, followers_count)
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica użytkowników – typ danych Profile

Observatory

Votes

Pobranie ostatnich 50 głosów na linki

Parametry metody
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica głosów

Comments

Pobranie ostatnich 25 komentarzy

Parametry metody
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica komentarzy – typ danych Comment

Entries

Pobranie ostatnich 25 wpisów z mikroblogu

Parametry metody
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica wpisów – typ danych Entry

EntriesComments

Pobranie ostatnich 25 komentarzy do wpisów

Parametry metody
Parametry API appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica komentarzy – typ danych EntryComment

Favorites

Index

Metoda wymaga prawa do profile

Pobranie listy ulubionych linków użytkownika

Parametry metody param1 - id listy
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca listę linków – format danych Link

Comments

Metoda wymaga prawa do profile

Pobranie listy ulubionych linków użytkownika

Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca listę komentarzy – format danych Comment

Entries

Metoda wymaga prawa do profile

Pobranie listy ulubionych linków użytkownika

Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica zawierająca listę wpisów – format danych Entry

Lists

Metoda wymaga prawa do profile

Pobranie list ulubionych użytkownika

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

tablica list

Stream

Index

Pobranie wpisów z Mikrobloga

Parametry metody
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę wpisów – format danych Entry

Hot

Pobranie "Gorących dyskusji" z Mikrobloga

Parametry metody
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

tablica zawierająca listę wpisów – format danych Entry

Tag

Index

Pobranie listy znalezisk i wpisów zawierających dany tag

Parametry metody param1 - nazwa tagu, bez znaku "#"
Parametry API appkey – klucz aplikacji
page – strona
Parametry POST

Odpowiedź:

Pole Wartość Typ
meta tag nazwa tagu string
is_observed czy użytkownik obserwuje tag bool
is_blocked czy użytkownik ignoruje tag bool
counters tablica zawierająca liczbę aktywności danego typu (total, entries, links) array
items tablica zawierająca listę linków i wpisów – format danych Mywykop string
Links

Pobranie listy znalezisk zawierających dany tag

Metoda działa analogicznie do tag/index.

Entries

Pobranie listy wpisów zawierających dany tag

Metoda działa analogicznie do tag/index.

Observe

Metoda wymaga prawa do profile

Rozpoczęcie obserwowania tagu

Parametry metody param1 - nazwa tagu, bez znaku "#"
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true – w przypadku sukcesu

Unobserve

Metoda wymaga prawa do profile

Usunięcie tagu z listy obserwowanych tagów

Parametry metody param1 - nazwa tagu, bez znaku "#"
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true – w przypadku sukcesu

Block

Metoda wymaga prawa do profile

Dodanie tagu do czarnej listy

Parametry metody param1 - nazwa tagu, bez znaku "#"
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true – w przypadku sukcesu

Unblock

Metoda wymaga prawa do profile

Usunięcie tagu z czarnej listy

Parametry metody param1 - nazwa tagu, bez znaku "#"
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true – w przypadku sukcesu

PM

Zasób udostępnia funkcjonalność Prywatnych Wiadomości

ConversationsList

Metoda wymaga prawa do pm

Pobranie listy konwersacji

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

Lista konwersacji – typ danych ConversationsList

Conversation

Metoda wymaga prawa do pm

Odczytanie wiadomości od użytkownika

Parametry metody param1 - nazwa użytkownika
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

Lista wiadomości – typ danych PMMessage

SendMessage

Metoda wymaga prawa do pm

Wysłanie wiadomości do użytkownika.

Parametry metody param1 - nazwa użytkownika
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST body - treść wpisu
embed - url do pliku graficznego lub filmu osadzonego w serwisie hostującym Wideo
Parametry FILE embed - plik graficzny który ma być osadzony w obiekcie (parametr nadpisuje url)

Odpowiedź:

true - w przypadku prawidłowo dodanego wpisu

DeleteConversation

Metoda wymaga prawa do pm

Usunięcie konwersacji z wybranym użytkownikiem

Parametry metody param1 - nazwa użytkownika
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

true - w przypadku prawidłowo usuniętej konwersacji

Tags

Lista tagów

Index

Pobranie listy popularnych tagów

Parametry metody
Parametry API userkey – klucz użytkownika
appkey – klucz aplikacji
Parametry POST

Odpowiedź:

Lista tagów – tablica [tag, count], gdzie tag to ciąg znaków określający tag, count to popularność tagu w ostatnim czasie

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
entries_comments ilość komentarzy do wpisów int
diggs ilość linków wykopanych int
buries ilość linków zakopanych int
related_links ilość linków powiązanych int
groups ilość grup których użytkownik jest członkiem int
avatar avatar uri
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
embed obrazek lub film dołączony do obiektu embed
link link do którego dodany jest komentarz (występuje tylko w metodzie profile/comments) Link

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
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
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
user_lists listy ulubionych na których znajduje się link int[]
plus18 link dla dorosłych bool
status
can_vote czy uzytkownik może głosować bool
has_own_content czy link ma treść bool
category domena grupy string
Poniżesz pola zostaną wypełnione jeśli do pytania o link lub listę linków zostanie 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

Relatedlink

Pole Wartość Typ
id identyfikator linku int
url adres URL linku uri
title tytuł linku string
plus18 link dla dorosłych bool
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
author login dodającego 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
link link do którego dodany jest link powiązany (występuje tylko w metodzie profile/related) Link

Mywykop

Pole Wartość Typ
type link string
Wpis link link
comments Tablica komentarzy comment
commented Czy obserwowani dodali komentarze bool
type entry string
Wpis entry

Entry

Pole Wartość Typ
id Identyfikator wpisu int
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 entrycomment
vote_count liczba głosów int
user_vote głos oddany przez użytkownika int
voters tablica głosujących użytkowników tablica obiektów typu dig
user_favorite true, jeśli użytkownik dodał wpis do ulubionych bool
embed obrazek lub film dołączony do obiektu embed

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
author_group Grupa autora int
date Data dodania komentarza date
body Treść komentarza string
vote_count liczba głosów int
user_vote głos oddany przez użytkownika int
voters tablica głosujących użytkowników tablica obiektów typu dig
embed obrazek lub film dołączony do obiektu embed
entry wpis do którego dodany jest komentarz (występuje tylko w metodzie profile/entriescomments) Entry

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
comment Informacja o komentarzu array
new Czy przeczytane bool
url URL do powiązanej akcji (np. konwersacji z prywatnych wiadomości czy odpowiedzi na zgłoszenie) uri

Notification type

Pole type w Notifications może przyjąć następujące wartości

Wartość Znaczenie
register zaproszony znajomy zarejestrował się w serwisie
observe użytkownik zaczął obserwację
unobserve użytkownik zakończył obserwację
entry_comment_directed komentarz do wpisu skierowany do użytkownika
entry_directed wpis skierowany do użytkownika
entry_tag wpis zawierający obserwowany tag
link_comment_directed komentarz w znalezisku skierowane do użytkownika
link_promoted link użytkownika dostał się na główną
link_directed znalezisko skierowane do użytkownika
system komunikat systemowy
badge nowe odznaczenie dla użytkownika
support_answer nowa odpowiedź w wątku w pomocy
channel_request zgłoszenie do kanału
channel_accepted zgłoszenie do kanału zaakceptowane
channel_rejected zgłoszenie do kanału odrzucone
pm wiadomość prywatna

Embed

Pole Wartość Typ
type image lub video string
preview miniatura obrazka lub filmu uri
url obrazek w pełnym rozmiarze lub filmu uri
source źródło w postaci nazwy pliku lub adresu źródłowego string/uri
plus18 treść dla dorosłych bool

ConversationsList

Pole Wartość Typ
last_update Data ostatniej wiadomości date
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
author_sex Płeć autora string
status Status wiadomości string (new, read)

PMMessage

Pole Wartość Typ
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
author_sex Płeć autora string
date Data ostatniej wiadomości date
body Treść wiadomości string
status Status wiadomości string (new, read)
direction Kierunek wiadomości string (sended, received)

Stałe

Grupa użytkownika

Wartość Znaczenie Kod koloru (hex)
0 Zielony #339933
1 Pomarańczowy #FF5917
2 Bordowy #BB0000
5 Administrator #000000
1001 Zbanowany #999999
1002 Usunięty #999999
2001 Klient #3F6FA0

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ę
5 Daily requests limit exceeded Limit żądań wyczerpany
6 Invalid API sign Niepoprawnie podpisane żądanie
7 This application does not have permission to do this Brak uprawnień do wykonania tej operacji
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
17 Your IP is banned Twoje IP jest zbanowane
18 Account is banned Konto zbanowane
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 user can't observe themself Użytkownik nie może obserwować samego siebie
34 You can't edit this comment Nie możesz edytować tego komentarza
35 You can't modify this comment or entry Nie możesz modyfikować tego komentarza
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
61 Entry doesn't exist or removed Wpis o podanym ID nie istnieje
71 Search query too short Ciąg wyszukiwania za krótki
81 Comment doesn\'t exist or removed Komentarz nie istnieje
999 Nice try ;-) Próba przechytrzenia aplikacji
1001 API is down, please be patient Przerwa serwisowa
1002 No index method defined Brak zdefiniowanego zasobu w żądaniu

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']))
{
	$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.

Podpisywanie żądań

function signUrl($url, $post = null)
{
	if ($post !== null) { ksort($post); }
	return md5(YourSecretApiKey . $url . ($post === null ? '' : implode(',', $post)));
}

Jeśli Twoja aplikacja wykorzystuje prawo do zapisu wszystkie żądania przekazywane do serwera muszą być podpisane. W tym celu należy wygenerowany dla żądania podpis przekazać jako nagłówek HTTP w polu apisign

Przykłady

Poniżej zamieszczona została przykładowa biblioteka do obsługi komunikacji z WykopAPI w języku PHP.

Biblioteka


<?php

/*
 * Wykop API
 * Biblioteka służy do obsługi API serwisu wykop.pl
 *
 * @author: maciejkiner
 * @version: 1.0
 */
class libs_Wapi
{
    protected 
$userAgent 'WykopAPI';
    protected 
$apiDomain 'http://a.wykop.pl/';
    protected 
$key null;
    protected 
$secret null;
    protected 
$userKey null;
    protected 
$format 'json';
    protected 
$output 'clear';
    protected 
$isValid;
    protected 
$error;
        
    
/*
     * Kontruktor
     *
     * @param string $key - appkey
     * @param string $secret - appsecret
     * @param string $output - output format
     * 
     */
    
public function __construct($key$secret$output null)
    {
        
$this->key $key;
        
$this->secret $secret;
        if (
$output !== null)
        {
            
$this->output $output;
        }
    }
    
    
/*
     * Wykonanie requestu do API
     *
     * @param string $action - zasób, np. "links/upcoming"
     * @param array $postData - post
     * @param array $filesData - pliki, np array('embed' => "@plik.jpg;type=image/jpeg")
     * 
     * @return array - odpowiedź API
     */
    
public function doRequest($action$postData null$filesData null)
    {
        
$url $this->apiDomain $action .= (strpos($action',') ? ',' '/') . $this->getKey() . $this->getFormat() . $this->getOutput() . $this->getUserKey();
        if (
$postData === null)
        {
            
$result $this->curl($url);
        }
        else
        {
            if (
$filesData !== null)
            {
                
$postData $filesData $postData;
            }
            
$result $this->curl($url$postData);
        }
        
$this->checkIsValid($result);
        return 
$this->isValid json_decode($result['content'], true) : array();
    }

    
/*
     * Czy zapytanie było poprawne
     *
     * @return bool - poprawna odpowiedź
     */
    
public function isValid()
    {
        return 
$this->isValid;
    }
    
    
/*
     * Błąd ostatniego zapytania
     *
     * @return string - komunikat błędu
     */
    
public function getError()
    {
        return 
$this->error;
    }
    
    
/*
     * Ustawienie klucza użytkownika - kolejne requesty będą wykonywane jako wybrany użytkownik
     *
     * @param string $userKey - klucz użytkownika
     */
    
public function setUserKey($userKey)
    {
        
$this->userKey $userKey;
    }

    
/*
     * Generuje link do Wykop Connect
     *
     * @param string $redirectUrl - opcjonalny adres przekierowania po zalogowaniu
     * @return string - link do Wykop Connect
     */
    
public function getConnectUrl($redirectUrl null)
    {
        
$url $this->apiDomain 'user/connect/' $this->getKey();
        if (
$redirectUrl !== null)
        {
            
$url .= 'redirect/' urlencode(base64_encode($redirectUrl)) . '/';
            
$url .= 'secure/' md5($this->secret $redirectUrl);
        }
        return 
$url;
    }
    
    
/*
     * Dekoduje dane connecta
     *
     * @return array - tablica z danymi connecta (appkey, login, token) - wykorzystywane później do logowania
     */
    
public function handleConnectData()
    {
        if (!empty(
$_GET['connectData']))
        {
            
$data base64_decode($_GET['connectData']);
            return 
json_decode($datatrue);
        }
    }
        
    protected function 
checkIsValid(&$result)
    {
        
$this->error null;
        if (empty(
$result['content']))
        {
            
$this->isValid false;
        } else {
            
$json json_decode($result['content'], true);
            if (!empty(
$json['error']))
            {
                
$this->isValid false;
                
$this->error $json['error']['message'];
            } else {
                
$this->isValid true;
            }
        }
    }
    
    protected function 
getUserKey()
    {
        if (!empty(
$this->userKey))
        {
            return 
'userkey/' $this->userKey '/';
        }
    }
    
    protected function 
getFormat()
    {
        if (!empty(
$this->format))
        {
            return 
'format/' $this->format '/';
        }
    }
    
    protected function 
getOutput()
    {
        if (!empty(
$this->output))
        {
            return 
'output/' $this->output '/';
        }
    }
    
    protected function 
getKey()
    {
        if (!empty(
$this->key))
        {
            return 
'appkey/' $this->key '/';
        }
    }    
    
    protected function 
sign($url$post null)
    {
        if (
$post !== null)
        {
            
ksort($post);
        }
        return 
md5($this->secret $url . ($post === null '' implode(','$post)));
    }
    
    protected function 
curl($url$post null)
    {
        
$options = array(
                
CURLOPT_RETURNTRANSFER     => true,
                
CURLOPT_HEADER             => false,
                
CURLOPT_ENCODING           => '',
                
CURLOPT_USERAGENT          => $this->userAgent,
                
CURLOPT_AUTOREFERER        => true,
                
CURLOPT_CONNECTTIMEOUT     => 15,
                
CURLOPT_TIMEOUT            => 15,
                
CURLOPT_MAXREDIRS          => 10,
                
CURLOPT_HTTPHEADER          => array('apisign:' $this->sign($url$post))
        );
         
        if (
$post !== null)
        {
            
$post_value is_array($post) ? http_build_query($post'f_' '&') : '';
            
$options[CURLOPT_POST] = 1;
            
$options[CURLOPT_POSTFIELDS] = $post;
        }

        
$ch  curl_init($url);
        
curl_setopt_array($ch$options);
        
$content curl_exec($ch);
        
$err curl_errno($ch);
        
$errmsg curl_error($ch);
        
$result curl_getinfo($ch);
        
curl_close($ch);
    
        
$result['errno'] = $err;
        
$result['errmsg'] = $errmsg;
        
$result['content'] = $content;         
        return 
$result;
    }
    
}

Przykład użycia

Przykładowa aplikacja pobiera zawartość strony głównej i wpisy z mikrobloga z tagiem suchar. Zakładamy, że skrypt znajduje się w katalogu głównym, a biblioteka wAPI w libs/Wapi.php


<?php

include('libs/Wapi.php');
// ustaw swój klucz i sekret
$wapi = new libs_Wapi('KLUCZ APLKACJI''SEKRET APLIKACJI');

echo 
'<h1>Strona główna</h1>';
$result $wapi->doRequest('links/promoted');
if (
$wapi->isValid())
{
    echo 
'<ul>';
    foreach (
$result as $r)
    {
        echo 
'<li>' $r['title'] . '</li>';
    }
    echo 
'</ul>';
} else {
    echo 
$wapi->getError();
}

echo 
'<h1>Dowcipy z mikrobloga</h1>';
$result $wapi->doRequest('search/entries', array('q' => '#suchar'));
if (
$wapi->isValid())
{
    echo 
'<ul>';
    foreach (
$result as $r)
    {
        echo 
'<li>' $r['body'] . '</li>';
    }
    echo 
'</ul>';
} else {
    echo 
$wapi->getError();
}