Wykop API

Transkrypt

Wykop API

Wykop API wersja 1.0
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....................................................................................................................................23
Vote................................................................................................................................................24
Stałe....................................................................................................................................................25
Grupa użytkownika........................................................................................................................25
Kody błędów..................................................................................................................................25
Przykłady............................................................................................................................................26
Wywołanie API..............................................................................................................................26
Pobranie listy linków.....................................................................................................................26
Dodanie komentarza......................................................................................................................27
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:
•
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.
7
•
parametry POST – 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 parametry metody. Metody wymagające prawa do zapisu zostały
oznaczone przez „Metoda wymaga praw do zapisu”.
Link
Index
Pobranie informacji o linku
Parametry:
parametry metody
param1 – identyfikator linka
parametry API
appkey – klucz aplikacji
userkey – klucz użytkownika
parametry POST
Tablica zawierająca dane o linku – format danych link
Comments
Pobranie listy komentarzy do linku
Parametry:
parametry metody
parametry API
parametry POST
Odpowiedź:
tablica zawierająca listę komentarzy – format danych comment
Reports
Pobranie zakopów
9
Parametry:
parametry metody
parametry API
parametry POST
Odpowiedź:
tablica zawierająca listę zakopów – format danych bury
Digs
Pobranie wykopów
Parametry:
parametry metody
parametry API
parametry POST
Odpowiedź:
tablica zawierająca listę wykopów – format danych dig
Related
Pobranie linków powiązanych
Parametry:
parametry metody
parametry API
userkey – klucz użytkownika
parametry POST
Odpowiedź:
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.
Parametry:
parametry metody
param1 – identyfikator linka w którym jest komentarz
parametry API
parametry POST
Odpowiedź:
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
Parametry:
parametry metody
parametry API
group – identyfikator grupy
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:
11
parametry metody
parametry API
group – identyfikator grupy
page – strona
sort – date (najnowsze), votes (wykopywane), comments (komentowane)
parametry POST
Odpowiedź:
Popular
Promoted
Pobranie linków ostatnio popularnych na stronie głównej
Parametry:
parametry metody
parametry API
parametry POST
Odpowiedź:
Upcoming
Pobranie linków ostatnio popularnych w wykopalisku
Parametry:
parametry metody
parametry API
parametry POST
Odpowiedź:
12
Profile
Index
Pobranie informacji o użytkowniku
Parametry:
parametry metody
param1 – nazwa użytkownika
parametry API
parametry POST
Odpowiedź:
tablica zawierająca dane o użytkowniku – format danych profile
Added
Pobranie linków dodanych przez użytkownika
Parametry:
parametry metody
parametry API
page – strona
parametry POST
Odpowiedź:
Groups
Pobranie listy grup których członkiem jest użytkownik
Parametry:
parametry metody
13
parametry API
page – strona
parametry POST
Odpowiedź:
tablica zawierająca listę grup – format danych groups
Published
Pobranie linków opublikowanych przez użytkownika
Parametry:
parametry metody
parametry API
page – strona
parametry POST
Odpowiedź:
Commented
Pobranie linków skomentowanych przez użytkownika
Parametry:
parametry metody
parametry API
page – strona
parametry POST
Odpowiedź:
14
Digged
Pobranie linków wykopanych przez użytkownika
Parametry:
parametry metody
parametry API
page – strona
parametry POST
Odpowiedź:
Search
Index
Pobranie wyników wyszukiwania
Parametry:
parametry metody
parametry API
page – strona
parametry POST
q – zapytanie do wyszukiwarki
Odpowiedź:
Groups
Index
Pobranie informacje o grupach
Parametry:
parametry metody
15
parametry API
group – idektyfikator grupy
page – numer strony listy grup
parametry POST
Odpowiedź:
lista grup – format danych group
Top
Index
Pobranie informacji o hitach roku
Parametry:
parametry metody
param1 – rok w formacie YYYY
parametry API
Odpowiedź:
tablica składająca się z dwunastu tablic linków – format danych link
Date
Pobranie informacje o hitach poszczególnych miesięcy
Parametry:
parametry metody
param1 – rok w formacie YYYY
param2 – miesiąc jako liczba od 1 do 12
parametry API
page - strona
Odpowiedź:
tablica linków – format danych link
Entries
Index
Pobranie pojedynczego wpisu
16
Parametry:
parametry metody
param1 – identyfikator wpisu
parametry API
parametry POST
Odpowiedź:
tablica wpisów – format danych entry
Rank
Index
Pobranie rankingu użytkowników
Parametry:
parametry metody
parametry API
page - strona
parametry POST
Odpowiedź:
tablica użytkowników – format danych profile
Observatory
Votes
Pobranie ostatnich 50 głosów na linki
Parametry:
parametry metody
parametry API
parametry POST
17
Odpowiedź:
tablica głosów – typ danych vote
Comments
Pobranie ostatnich 25 komentarzy
Parametry:
parametry metody
parametry API
parametry POST
Odpowiedź:
tablica komentarzy – format danych comment
Entries
Pobranie ostatnich 25 wpisów z mikroblogu
Parametry:
parametry metody
parametry API
parametry POST
Odpowiedź:
tablica wpisów – format danych entry
18
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
avatar
avatar
uri
avatar_lo
avatar (mały rozmiar)
uri
avatar_med
avatar (średni rozmiar)
uri
is_observed
czy aktualny użytkownik obserwuje tego użytkownika
bool
19
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
Pole
Wartość
Typ
reason
identyfikator powodu zakopu
int
author
autor
string
author_avatar
avatar autora
uri
Bury
uri
author_avatar_lo
uri
author_group
grupa autora
int
Pole
Wartość
Typ
author
autor
string
author_avatar
avatar autora
uri
Dig
uri
author_avatar_lo
uri
author_group
grupa autora
int
20
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
uri
author_avatar_lo
uri
author_group
grupa autora
int
preview
miniatura
uri
plus18
link dla dorosłych
bool
can_vote
czy uzytkownik może głosować
bool
has_own_content
czy link ma treść
bool
status
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
21
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
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
Relatedlink
Mywykop
Wpisy z mojego wykopu dzielą się na dwa rodzaje
Pole
Wartość
Typ
type
link
string
Wpis link
link
comments
Tablica komentarzy
comment
commented
Czy obserwowani dodali komentarze
bool
22
Pole
Wartość
Typ
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
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
uri
author_group
Grupa autora
int
date
Data dodania komentarza
date
body
Treść komentarza
string
Wartość
Typ
Notification
Pole
23
author
Autor komentarza
string
author_avatar
Avatar autora
uri
author_avatar_med Avatar autora (średni rozmiar)
uri
author_avatar_lo
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
Pole
Wartość
Typ
link_id
Identyfikator linka
int
type
Typ głosy, „dig” lub „bury”
string
date
Data akcji
date
Vote
24
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
permission to write
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,
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
komentarze
32
Invalid link ID
Niepoprawny identyfikator linku
33
You cann't observe themeself
Użytkownik nie może obserwować samego siebie
not
have Aplikacja bez prawa do zapisu próbuje wywołać
niedozwoloną metodę
25
nie
może
głosować
na
możliwe
własne
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']))
26
{
}
$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.
27

Wykop API

Transkrypt

Podobne dokumenty

stowarzyszenie siedmiu

Mobile + Kontekst Otoczenia

Instrukcja integracji HP Wall Art ze stroną www

Dr Piotr Kotlarz Wydział Technologiczny Instytut Informatyki i

Tytuł szkolenia: HTML5 API dla programistów JavaScript