Table of Contents
|
Wstęp
Interfejs programistyczny (API) serwisu Blip.pl umożliwia tworzenie aplikacji wykorzystujących zasoby i logikę serwisu osobom trzecim. Dokładamy wszelkich starań, by tworzenie różnego rodzaju programów czy widgetów wokół Blip.pl, było jak najłatwiejsze, dlatego chętnie wysłuchamy Waszych uwag i propozycji usprawnień, które można kierować pod adres lp.pilb|pilb#lp.pilb|pilb.
Dla programistów używających API stworzona została grupa dyskusyjna blip-devel, służąca wymianie doświaczeń przy pisaniu aplikacji współpracujących z Blip.pl. Jest ona dostępna także jako lista mailingowa. Gotowe aplikacje i biblioteki należy dopisywać na odpowiedniej stronie blipowego wiki, podając dane kontaktowe autora. Wiki można wykorzystać także do publikowania dokumentacji gotowych aplikacji.
Warunki użytkowania
Administratorzy serwisu Blip.pl rezerwują sobie prawo do wyłączenia części lub całości API, blokowania użytkowników bez podawania przyczyn i dowolnej modyfikacji zasad dostępu oraz wprowadzania ograniczeń, przede wszystkim z powodu nadużyć różnej formy.
Blipowe dodatki
Udostępniliśmy loga serwisu Blip.pl do wykorzystania w aplikacjach, rezerwując sobie jednocześnie prawo do odwołania domniemanej zgody na użycie loga w przypadku, gdy zostanie ono zastosowane w celach sprzecznych z interesami właścieciela serwisu Blip.pl lub łamiącymi obowiązujące prawo. Dostępne są także loga w innych formatach i innych wielkościach, zainteresowanych prosimy o kontakt mailowy.
Biblioteki
Osoby zainteresowane szybkim stworzeniem aplikacji współpracującej z Blip.pl powinny sprawdzić, czy dla wybranego języka programowania/frameworku nie jest już dostępna gotowa biblioteka. Należy też upewnić się czy obsługuje ona aktualną wersję API.
Ogólna struktura API
Architektura intefejsu programistycznego Blip.pl wykonana jest zgodnie ze wskazaniami stylu REST, w związku z czym cała komunikacja korzysta z protokołu HTTP, a możliwe rodzaje interakcji reprezentowane są poprzez zasoby oraz przyporządkowane im operacje. Aby korzystać z opisywanego w niniejszym dokumencie API należy obligatoryjnie ustawiać nagłówek X-Blip-API na wartość 0.02, oraz nagłówek Accept na typ MIME pożądanego formatu odpowiedzi (obecnie tylko i wyłącznie application/json).
Identyfikacja klienta odbywa się poprzez nagłówek User-Agent: (lub alternatywnie X-Blip-Application:), który wykorzystujemy do celów statystycznych. Choć jego ustawienie nie jest wymagane, to leży ono w interesie samego twórcy aplikacji, pomagając w jej promocji. W nagłówku warto także umieścić informacje pozwalające na skontaktowanie się z twórcą aplikacji.
Korzystanie z części dostępnych zasobów i operacji wymaga wcześniejszej uwierzytelnienia. Obecnie odbywa się to zgodnie ze schematem HTTP Basic, w którym login zostaje połączony z hasłem poprzez znak dwukropka, a następnie wynikowy napis zostaje przekształcony do formatu Base64 i przesłany w nagłówku Authorization: z prefiksem Basic, oznaczającym rodzaj uwierzytelnienia. Dla przykładu prawidłowy nagłówek uwierzytelniający, dla użytkownika "stefan" z hasłem "plecy.8" wygląda w następujący sposób:
Authorization: Basic c3RlZmFuOnBsZWN5Ljg=
Możliwe jest także uwierzytelnianie użytkowników przy użyciu OAuth.
Flash
Plik crossdomain.xml dla aplikacji flashowych znajduje się w subdomenie w.blip.pl.
Formaty danych
W przypadku zapytań PUT i POST dane przyjmowane są w postaci parametrów zakodowanych w formie danych formularza lub w postaci JSONa. Dane zwracane są zawsze w formacie JSON, zakodowanym w UTF-8. Mimo to niezbędne jest ustawienie nagłówka Accept: na application/json, w przeciwnym wypadku możemy bowiem otrzymać po prostu HTML jednej ze stron serwisu.
Relacje pomiędzy zasobami
Powiązania pomiędzy udostępnianymi przez API zasobami określone są poprzez klucze z końcówką _path w ich reprezentacjach, których wartościami są adresy URL umożliwiające pobranie reprezentacji JSON danego zasobu powiązanego. I tak np. reprezentacja zasobu User posiada klucz background_path, którego wartością jest adres z którego można pobrać JSON reprezentujący tło danego użytkownika. Niekiedy powiązania pomiędzy zasobami są na tyle silne, że prawie zawsze klient potrzebuje ich razem. W takim przypadku API zagnieżdża reprezentację jednego zasobu w reprezentacji drugiego - np. JSON danego statusu zawiera klucz user, pod którym znajduje się JSON reprezentujący autora statusu.
Obsługa metod HTTP
W kilku przypadkach bywa tak, że różne operacje dostępne są pod tym samym adresem url, a rodzaj żądania jest rozpoznawany na postawie nagłówka HTTP. Zgodnie z konwencją przyjetą dla serwisów RESTowych, żądanie typu POST odpowiada tworzeniu nowego obiektu, PUT jego uaktualnieniu, DELETE usunięciu, a GET pobraniu reprezentacji w odpowiednim formacie.
W przypadku jakichkolwiek problemów z dokonywaniem zapytań danego rodzaju, możliwe jest wykonanie zapytania POST z polem _method ustawionym na nazwę odpowiedniego żadania HTTP - jest to rozwiązanie niezbędne m. in. do komunikacji z Flashem, który nie potrafi poprawnie ustawiać nagłówków HTTP dla zapytań innych niż POST.
Dodatkowe parametry
Należy także pamiętać, że część akcji zwracających listy obiektów posiada parametr limit, o maksymalnej i jednocześnie domyślnej wartości 50, oznaczającej maksymalną ilość zasóbów do zwrócenia. Parametr offset pozwala cofnąć się w czasie o x statusów, co umożliwia np. implementację stronicowania w aplikacji klienckiej.
W przypadku zastosowań w których liczba requestów ma znaczenia, dostępny jest parametr include, pozwalający na umieszczenie reprezentacji zasobów powiązanych bezpośrednio w reprezentacji "głównego" zasobu, zamiast klucza z końcówką _path i wartością będąca urlem danego zasobu. Zachowuje to przejrzystość domyślnej reprezentacji, jednocześnie pozwalając twórcom aplikacji na dostosowanie szczegółowości zwracanych danych do własnych potrzeb. I tak, zakładając że pobieramy update, bez parametru include nie otrzymamy bezpośrednio danych nagrań i obrazków z nim powiązanych, lecz recording_path i pictures_path, czyli URL-e pod którymi są one dostępne. Jeśli zaś ustawimy include na recording,pictures, wszelkie dane dostępne pod tymi URL-ami zostaną umieszczone bezpośrednio w treści odpowiedzi - jako wartości powiązane z kluczami recording i pictures. Można rozwijać zasoby głębiej niż tylko na pierwszym poziomie - np. aby otrzymać zarówno obiekt JSON odbiorcy wiadomości, jak i jego awatara, możemy ustawić include na recipient,recipient[avatar].
W przypadku korzystania z API za pomocą języka JavaScript, kluczowe są także opcjonalne parametry variable i callback. Jako, że Same Origin Policy przeglądarki nie zezwala na wykonywanie żądań XmlHttpRequest do innych domen niż ta, z której pochodzi dokument, konieczne jest użycie techniki znanej jako JSON-P. Aby otrzymać w swojej aplikacji dane, należy:
- Dołączyć rozszerzenie ".json" do urla akcji, w zastępstwie nagłówka Accept np. wywołanie http://api.blip.pl/updates?limit=20 zastępujemy http://api.blip.pl/updates.json?limit=20
- Wstawić do dokumentu HTML tag <script>, odwołujący się do urla odpowiedniej akcji API, wraz z parametrami callback, variable, lub oboma z nich.
W zależności od podanych parametrów wyróżniamy następujące sytuacje:
- Obecny jedynie parametr callback - otrzymane dane zostaną przekazane funkcji o nazwie będącą wartością parametru callback jako pierwszy argument.
- Obecny jedynie parametr variable - otrzymane dane zostaną przypisane zmiennej o nazwie będącą wartością parametru variable.
- Obecne jednocześnie parametry callback oraz variable - otrzymane dane zostaną przypisane zmiennej o nazwie będącą wartością parametru variable, po czym zostanie wykonana funkcja o nazwie z parametru callback. Będzie to wywołanie pozbawione argumentów.
Jednocześnie, ustawienie paremetru callback lub variable, skutkuje nieco inną formą odpowiedzi - wszędzie tam gdzie w innych przypadkach zwracane jest 204 No Content, dostajemy 200 OK i callback/przypisanie na pustą tablicę lub ewentualnie pusty literał JSON. Jest to związane z wyżej wymienioną techniką pobierania odpowiedzi z API, która uniemożliwia odczytywanie kodów odpowiedzi.
Odpowiedzi
O tym jaki rezultat przyniosła dana operacja najbardziej skrótowo informuje numer nagłówka HTTP zwróconej przez serwer odpowiedzi. Przyjęta została następująca konwencja:
- 200 OK
- Przy zapytaniach GET, PUT i DELETE - pomyślne wykonanie żądanej operacji.
- 201 Created
- Przy zapytaniach POST, oznacza poprawne utworzenie nowego obiektu. Nagłówek Location odpowiedzi wskazuje adres URL nowo utworzonego zasobu.
- 204 No Content
- Zapytanie jest poprawne, jednak nie ma treści do zwrócenia. Np. zapytanie o subskrybcje, kiedy nikogo nie subskrybujesz.
- 400 Bad Request
- Przy próbie pobrania zbyt dużej ilości danych na raz, najczęściej przy ustawieniu limitu większego niż maksymalny. Także przy nieprawidłowej próbie utworzenia zasobu - zbyt długa wiadomość / status (powyżej 160 znaków), nieistniejący odbiorca wiadomości.
- 401 Unauthorized
- Przy próbie dostępu do zasobu do którego klient nie ma uprawnień - np. brak uwierzytelnienia w akcjach którego tego wymagają.
- 404 Missing
- Zasób który próbuje uzyskać klient nie istnieje - np. zapytanie o statusy użytkownika, którego nie ma w serwisie.
- 422 Unprocessable Entity
- Zestaw danych w żądaniu PUT lub POST jest nieprawidłowy, bądź dostarczone dane nie spełniają wymagań składniowych.
- 503 Server Unavailable
- Serwer jest przeciążony, niedostępny, lub klient zbyt często wysyła zapytania. Należy ponowić próbę za jakiś czas.
Dla obsługi sytuacji, w których obsługa kodów HTTP jest niemożliwa lub utrudniona, cześć wywołań w przypadku wystąpienia błędu dodatkowo zwraca w treści odpowiedzi obiekt błędu w formacie JSON. Szczególnie, w sytuacji kiedy ustawiony jest parametr callback lub variable, a nie została dokonana autoryzacja, zwracany jest następujący błąd:
{"error": {"name": "unauthorized"}}
oznaczający oczywiście brak uwierzytelnienia. Podobnie, jako że nie da się załadować jako <script> odpowiedzi o kodzie 400, w przypadku ustawienia parametrów callback lub/i variable zamiast niej zwrócony zostanie kod 200 i treść:
{"error": {"name": "bad_request"}}
Typy wiadomości
W zasobach zwracających wiadomości wyróżniane są następujące typy wiadomości (pole type w strukturze JSON):
- Status
- Status
- DirectedMessage
- Publiczna wiadomość kierowana
- PrivateMessage
- Prywatna wiadomość kierowana
- Notice
- Powiadomienie
- UpdateTip
- Wskazówki dla nowych użytkowników
Pliki graficzne
Obrazki załączane do wiadomości dostępne są w rozmiarach:
- standard
- 90x90 pikseli
- inmsg
- 380x380 pikseli
- full
- 720x720 pikseli
Tła dostępne są w rozmiarach:
- standard
- 90x90 pikseli
- large
- 120x120 pikseli
Awatary dostępne są w rozmiarach:
- femto
- 15x15 pikseli
- nano
- 30x30 pikseli
- pico
- 50x50 pikseli
- standard
- 90x90 pikseli
- large
- 120x120 pikseli
Jeżeli przesłany do Blipa plik jest w formacie innym niż JPG, to jego oryginał zachowany będzie z rozszerzeniem odpowiadającym jego typowi, na przykład:
$ curl -v -H'Accept: application/json' -H'X-Blip-API: 0.02' http://api.blip.pl/updates/187790591/pictures
* About to connect() to api.blip.pl port 80 (#0)
* Trying 91.197.13.171... connected
* Connected to api.blip.pl (91.197.13.171) port 80 (#0)
> GET /updates/187790591/pictures HTTP/1.1
> User-Agent: curl/7.21.0 (i686-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
> Host: api.blip.pl
> Accept: application/json
> X-Blip-API: 0.02
>
< HTTP/1.1 200 OK
< Date: Fri, 15 Oct 2010 09:51:59 GMT
< Server: Apache/2.2.3 (Debian) Phusion_Passenger/2.2.11
< X-Powered-By: Phusion Passenger (mod_rails/mod_rack) 2.2.11
< ETag: "0bb26b7910badd209fbe4ee166d72138"
< X-Runtime: 15
< Cache-Control: private, max-age=0, must-revalidate
< Content-Length: 117
< Status: 200
< Connection: close
< Content-Type: application/json; charset=utf-8
<
* Closing connection #0
[{"update_path":"/updates/187790591","id":1368563,"url":"http://blip.pl/user_generated/update_pictures/1368563.gif"}]
Wszystkie miniaturki konwertowane są do formatu JPG - aby pobrać ten plik w rozmiarze standard należy odwołać się do adresu http://blip.pl/user_generated/update_pictures/1368563_standard.jpg
Nie dotyczy to plików graficznych załączanych do prywatnych wiadomości:
$ curl -v -H'Accept: application/json' -H'X-Blip-API: 0.02' -u "frania:hwdp" "http://api.blip.pl/pm/189988153?include=pictures"
* About to connect() to api.blip.pl port 80 (#0)
* Trying 91.197.13.171... connected
* Connected to api.blip.pl (91.197.13.171) port 80 (#0)
* Server auth using Basic with user 'frania'
> GET /pm/189988153?include=pictures HTTP/1.1
> User-Agent: curl/7.21.0 (i686-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
> Host: api.blip.pl
> Accept: application/json
> X-Blip-API: 0.02
>
< HTTP/1.1 200 OK
< Date: Mon, 18 Oct 2010 08:16:50 GMT
< Server: Apache/2.2.3 (Debian) Phusion_Passenger/2.2.11
< X-Powered-By: Phusion Passenger (mod_rails/mod_rack) 2.2.11
< ETag: "bd02a30ab096b949c9dd5dcfd4ed5485"
< X-Runtime: 19
< Cache-Control: private, max-age=0, must-revalidate
< Content-Length: 301
< Status: 200
< Connection: close
< Content-Type: application/json; charset=utf-8
<
* Closing connection #0
{"type":"PrivateMessage","pictures":[{"id":1375357,"url":"http://blip.pl/secure_picture/1375357/"}],"transport":{"name":"www","id":6},"recipient_path":"/users/frania","created_at":"2010-10-18 10:09:01","body":"Witaj.","id":189988153,"user_path":"/users/frania","transport_description":"WWW"}
Aby pobrać miniaturkę w formacie standard należy odwołać się do adresu http://blip.pl/secure_picture/1375357/standard
Awatary
Awatar każdego użytkownika można pobrać bezpośrednio za pomocą odpowiedniego adresu URL, na przykład: http://blip.pl/users/blip/avatar/atto.jpg. Jeżeli użytkownik nie posiada załadowanego awatara zwrócony zostanie domyślny obrazek.
Cache tego zasobu czyszczony jest periodycznie - zmiana awatara w aplikacji będzie widoczna najpóźniej w ciągu 2 godzin.
Zapytanie
Zapytanie o awatar ma format:
http://blip.pl/users/jack/avatar/atto.jpg
gdzie:
- jack
- Login użytkownika
- size
- Rozmiar awatara
Dostępne rozmiary awatarów
- femto
- 15x15 pikseli
- nano
- 30x30 pikseli
- pico
- 50x50 pikseli
- standard
- 90x90 pikseli
- large
- 120x120 pikseli
Lista zasobów
Updates
(Wymaga uwierzytelnienia)
Pod określeniem update rozumiemy dowolną wiadomość utworzoną w ramach serwisu - zarówno status jak i wiadomość kierowaną (od jednego użytkownika do drugiego). Zasób ten stanowi trzon całego API, jednocześnie zasoby Status, DirectedMessage i PrivateMessage są właściwie jedynie swego rodzaju "filtrami", pozwalającymi wykonywać operacje tylko na wiadomościach, bądź tylko na statusach, implementując jednak identyczny interfejs (pomijając rozróżnianie prefiksu ">odbiorca:" przy tworzeniu wiadomości za pomocą zasobu update). Sposób użycia każdego z tych zasobów najprościej zrozumieć za pomocą paru prostych zasad:
- Statusy/wiadomości danego użytkownika znajdują się pod adresem URL: /users/foo/[updates,statuses,directed_messages]
- Statusy/wiadomości wszystkich użytkowników znajdują się pod adresem URL: /[updates,statuses,directed_messages]/all
- Jako skrót, pozostałe akcje znajdującę się pod /[updates,statuses,directed_messages], gdy nie został podany przedrostek /users/[nazwauzytkownika] przyjmują że chodzi o użytkownika obecnie zautentykowanego.
- Wszystkie akcje posiadają odpowiedniki ze słowem since, umożliwiające twórcom aplikacji dynamiczne odświeżanie treści wraz z upływem czasu (powtarzający się co jakiś czas "poll" o nową treść).
Operacje
- POST /updates
- Tworzy nową wiadomość, rozróżniając wiadomości od statusów po prefiksie ">ktos:"
- GET /updates?limit=20
- Zwraca do 20 najnowszych wiadomości uwierzytelnionego usera (opcjonalny parametr offset)
- GET /updates/50/since
- Zwraca wszystkie wiadomości bieżącego użytkownika nowsze od wiadomości o id równym 50
- GET /updates/all?limit=20
- Zwraca 20 najnowszych wiadomości od wszystkich użytkowników (opcjonalny parametr offset)
- GET /updates/50/all_since?limit=20
- Zwraca 20 najnowszych wiadomości od wszystkich użytkowników nowszych od wiadomości o id równym 50
- GET /users/jack/updates?limit=20
- Zwraca do 20 najnowszych wiadomości użytkownika jack
- GET /users/jack/updates/3/since
- Zwraca wszystkie wiadomości użytkownika jack nowsze od wiadomości o id równym 3
- GET /updates/5
- Zwraca wiadomości o id równym 5
- DELETE /updates/5
- Kasuje wiadomość o id równym 5
Reprezentacja JSON
{
"id": 1,
"created_at": "2007-10-18 11:27:20",
"transport": { "id": 7, "name": "api" },
"transport_description": "BlipFox",
"body": "foobar http://rdir.pl/jk2hg",
"type": "Status",
"user_path": "/users/frania",
"pictures_path": "/updates/1/pictures",
"recording_path": "/updates/1/recording",
"movie_path": "/updates/12/movie"
}
Pola pictures_path, recording_path i movie_path występują w reprezentacji tylko i wyłącznie wtedy, kiedy do wiadomości dołączone są odpowiednio obrazki, nagranie lub film.
Pole transport_description generowane będzie na podstawie nagłówka User-Agent i wpisów w bazie. Dla aplikacji korzystających z OAuth pole transport_description generowane będzie na podstawie opisu aplikacji.
Tworzenie
Zasób Updates akceptuje następujące parametry przy wykonywaniu zapytania typu POST:
- update[body]
- Treść tworzonej wadomość, wraz z opcjonalnym prefiksem ">odbiorca:", który sprawia że tworzona jest wiadomość kierowana zamiast statusu
- update[picture]
- Obrazek do załączenia do wiadomości
Przykładowe użycie
Utworzenie statusu o treści "elo-pld":
$ curl -v -H'Accept: application/json' -H'X-Blip-api: 0.02'
-u foo:s0p3l -F "update[body]=elo-pld" http://api.blip.pl/updates
* About to connect() to api.blip.pl port 80
* Trying 85.232.236.216... * connected
* Connected to api.blip.pl (85.232.236.216) port 80
* Server auth using Basic with user 'foo'
> POST /updates HTTP/1.1
Authorization: Basic Zm9vOnMwcDNs==
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1
OpenSSL/0.9.7l zlib/1.2.3
Host: api.blip.pl
Pragma: no-cache
Accept: application/json
X-Blip-api: 0.02
Content-Length: 146
Expect: 100-continue
Content-Type: multipart/form-data;
boundary=----------------------------49950f0df8f7
Pobranie wiadomości o numerze 345672:
$ curl -v -H'Accept: application/json' -H'X-Blip-api: 0.02'
-u foo:s0p3l http://api.blip.pl/updates/345672
* About to connect() to api.blip.pl port 80
* Trying 85.232.236.216... * connected
* Connected to api.blip.pl (85.232.236.216) port 80
* Server auth using Basic with user 'foo'
> GET /updates/345672 HTTP/1.1
Authorization: Basic Zm9vOnMwcDNs==
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1
OpenSSL/0.9.7l zlib/1.2.3
Host: api.blip.pl
Pragma: no-cache
Accept: application/json
X-Blip-api: 0.02
Directed Messages
(Wymaga uwierzytelnienia)
Operacje
- POST /directed_messages
- Tworzy nową wiadomość kierowaną, nie przyjmuje prefiksu
- GET /directed_messages?limit=20
- Pobiera do 20 najnowszych wiadomości kierowanych do lub od bieżącego użytkownika
- GET /directed_messages/50/since
- Pobiera wszystkie wiadomości kierowane do lub od bieżącego użytkownika nowsze od wiadomości z id równym 50
- GET /directed_messages/all?limit=20
- Pobiera do 20 najnowszych wiadomości kierowanych wszystkich użytkowników
- GET /directed_messages/50/all_since?limit=20
- Pobiera do 20 najnowszych wiadomości kierowanych wszystkich użytkowników nowsze od wiadomości z id równym 50
- GET /users/jack/directed_messages?limit=50
- Pobiera do 50 ostatnich wiadomości kierowanych użytkownika jack
- GET /users/jack/directed_messages/12/since
- Pobiera wszystkie wiadomości kierowane do użytkownika jack nowsze od wiadomości z id równym 12
- GET /directed_messages/5
- Pobiera wiadomość kierowaną o id równym 5
- DELETE /directed_messages/5
- Usuwa wiadomość kierowaną o id równym 5
Reprezentacja JSON
{
"id": 1,
"created_at": "2007-10-18 11:27:20",
"transport": { "id": 6, "name": "www"},
"body": "Witaj heniek!",
"type": "DirectedMessage",
"user_path": "/users/jakisnadawca",
"recipient_path": "/users/jakisodbiorca"
}
Tworzenie
Zasób DirectedMessage akceptuje następujące parametry przy wykonywaniu zapytania typu POST:
- directed_message[body]
- Treść tworzonej wiadomości, bez prefiksu wskazującego odbiorcę
- directed_message[recipient]
- Login lub liczbowe id odbiorcy wiadomości
- directed_message[picture]
- Obrazek do załączenia do wiadomości
Statuses
(Nie wymaga uwierzytelnienia)
Operacje
- POST /statuses
- Tworzy nowy status, nie przyjmuje prefiksu
- GET /statuses?limit=50
- Zwraca do 50 ostatnich statusów bieżącego użytkownika
- GET /statuses/20/since
- Zwraca statusy bieżącego użytkownika nowsze od statusu o id równym 20
- GET /statuses/all?limit=20
- Zwraca 20 najnowszych statusów od wszystkich użytkowników
- GET /statuses/20/all_since?limit=20
- Zwraca 20 najstarszych statusów od wszystkich użytkowników nowszych od statusu z id równym 20
- GET /users/jack/statuses?limit=50
- Zwraca 50 ostatnich statusów użytkownika jack
- GET /users/jack/statuses/5/since
- Pokazuje statusy użytkownika jack, nowsze od statusu o id równym 5
- GET /statuses/5
- Zwraca status o id równym 5
- DELETE /statuses/5
- Usuwa status o id równym 5
Reprezentacja JSON
{
"id": 1,
"created_at": "2007-10-18 11:27:20",
"transport": { "id": 6, "name": "www" },
"body": "foobar http://rdir.pl/jk2hg",
"type": "Status",
"user_path": "/users/frania"
}
Tworzenie
Zasób Status akceptuje następujące parametry przy wykonywaniu zapytania typu POST:
- status[body]
- Treść tworzonego statusu
- status[picture]
- Obrazek do załączenia do statusu
Archives
(Nie wymaga uwierzytelnienia)
Wyniki zwracane przez te metody mogą się zmienić po wdrożeniu #nowyblip.
Operacje
- GET /users/jack/archives
- Zwraca ostatnie wiadomości z archiwum użytkownika jack
- GET /users/jack/archives/2010/11
- Zwraca ostatnie wiadomości z archiwum użytkownika jack z 11 miesiąca 2010 roku
Reprezentacja JSON
{
"id": 1,
"created_at": "2007-10-18 11:27:20",
"transport": { "id": 6, "name": "www" },
"body": "foobar http://rdir.pl/jk2hg",
"type": "Status",
"user_path": "/users/frania"
}
Private Messages
(Wymaga uwierzytelnienia)
Operacje
- GET /private_messages?limit=20
- Pobiera do 20 najnowszych prywatnych wiadomości do lub od bieżącego użytkownika
- GET /private_messages/since/50
- Pobiera wszytkie prywatne wiadomości do lub od bieżącego użytkownika nowsze od wiadomości z id równym 50
- GET /private_messages/5
- Pobiera wiadomość prywatną o id równym 5
- DELETE /private_messages/5
- Usuwa wiadomość prywatną o id równym 5
Reprezentacja JSON
{
"id": 1,
"created_at": "2008-08-18 17:27:20",
"transport": { "id": 6, "name": "www" },
"body": "Prywatne siema!",
"type": "PrivateMessage",
"user_path": "/users/jakisnadawca",
"recipient_path": "/users/jakisodbiorca"
}
Tworzenie
Zasób PrivateMessage akceptuje następujące parametry przy wykonywaniu zapytania typu POST:
- private_message[body]
- Treść tworzonej wiadomości, bez prefisku wskazującego odbiorcę
- private_message[recipient]
- Login lub liczbowe id odbiorcy wiadomości
- private_message[picture]
- Obrazek do załączenia do wiadomości
Notices
(Wymaga uwierzytelnienia)
Operacje
- GET /notices?limit=20
- Pobiera do 20 najnowszych powiadomień bieżącego użytkownika
- GET /notices/since/50
- Pobiera wszytkie powiadomienia bieżącego użytkownika nowsze od wiadomości z id równym 50
- GET /notices/all?limit=20
- Zwraca 20 najnowszych powiadomień do wszystkich użytkowników
- GET /notices/20/all_since?limit=20
- Zwraca 20 najstarszych powiadomień do wszystkich użytkowników nowszych od wiadomości z id równym 20
- GET /users/jack/notices?limit=50
- Zwraca 50 ostatnich powiadomień użytkownika jack
- GET /users/jack/notices/5/since
- Pokazuje powiadomienia użytkownika jack, nowsze od wiadomości z id równym 5
- GET /notices/5
- Zwraca powiadomienie o id 5
Tags
(Nie wymaga uwierzytelnienia)
Operacje
- GET /tags/foobar?limit=20
- Zwraca do 20 najnowszych statusów otagowanych "foobar" (opcjonalny parametr offset)
- GET /tags/foobar/since/10
- Zwraca do wszystkie statusy otagowane "foobar" nowsze od statusu o id równym 10
Movie
(Nie wymaga uwierzytelnienia)
Operacje
Przykładowe użycie
$ curl -v -H'Accept: application/json' -H'X-Blip-api: 0.02'
http://api.blip.pl/updates/363884/movie
* About to connect() to api.blip.pl port 80
* Trying 85.232.236.216... * connected
* Connected to api.blip.pl (85.232.236.216) port 80
> GET /updates/272707/movie HTTP/1.1
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1
OpenSSL/0.9.7l zlib/1.2.3
Host: api.blip.pl
Pragma: no-cache
Accept: application/json
X-Blip-api: 0.02
Reprezentacja JSON
{
"url": "http://blip.pl/user_generated/movie/12.flv",
"id": 12
}
Recording
(Nie wymaga uwierzytelnienia)
Operacje
- GET /updates/123/recording
- Zwraca nagranie skojarzone z wiadomością o id równym 123
Przykładowe użycie
$ curl -v -H'Accept: application/json' -H'X-Blip-api: 0.02'
http://api.blip.pl/updates/363884/recording
* About to connect() to api.blip.pl port 80
* Trying 85.232.236.216... * connected
* Connected to api.blip.pl (85.232.236.216) port 80
> GET /updates/272707/recording HTTP/1.1
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1
OpenSSL/0.9.7l zlib/1.2.3
Host: api.blip.pl
Pragma: no-cache
Accept: application/json
X-Blip-api: 0.02
Reprezentacja JSON
{
"url": "http://blip.pl/user_generated/recordings/138.mp3",
"id": 138
}
Pictures
(Nie wymaga uwierzytelnienia)
Operacje
- GET /updates/123/pictures
- Zwraca listę obrazków należących do wiadomości o id równym 123
- GET /pictures/all?limit=20
- Zwraca 20 najnowszych obrazków od wszystkich użytkowników
- GET /pictures/20/all_since?limit=20
- Zwraca 20 najstarszych obrazków od wszystkich użytkowników nowszych od obrazka o id równym 20
Reprezentacja JSON
Dla statusów i wiadomości kierowanych:
{
"id": 12086,
"url": "http://blip.pl/user_generated/update_pictures/12086.jpg",
"update_path": "http://api.blip.pl/updates/1234"
}
Klucz update_path nie pojawia się w reprezentacji obrazków zwracanych dla już zadanej wiadomości (w wywołaniu /updates/321/pictures).
Dla wiadomości prywatnych (wymaga uwierzytelnienia):
{
"id": 12087,
"url": "http://blip.pl/secure_picture/12087"
}
Przykładowe użycie
$ curl -v -H'Accept: application/json' -H'X-Blip-api: 0.02'
http://api.blip.pl/updates/272762/pictures
* About to connect() to api.blip.pl port 80
* Trying 85.232.236.216... * connected
* Connected to api.blip.pl (85.232.236.216) port 80
> GET /updates/272762/pictures HTTP/1.1
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1
OpenSSL/0.9.7l zlib/1.2.3
Host: api.blip.pl
Pragma: no-cache
Accept: application/json
X-Blip-api: 0.02
Shortlinks
(Odczyt nie wymaga uwierzytelnienia)
Operacje
- GET /shortlinks/xyz
- Zwraca odnośnik http://rdir.pl/xyz
- POST /shortlinks
- Tworzy odnośnik (rdir.pl). Uwaga! Wymaga uwierzytelnienia
- GET /shortlinks/all?limit=20
- Zwraca 20 najnowszych odnośników (rdir.pl) od wszystkich użytkowników
- GET /shortlinks/20/all_since?limit=20
- Zwraca 20 najstarszych odnośników od wszystkich użytkowników nowszych od odnośnika o id równym 20
Reprezentacja JSON
{
"id": 34190,
"created_at": "2007-12-03 04:16:03",
"hit_count': 2,
"original_link": "http://info.gadu-gadu.pl/uslugi/blip",
"shortcode": "swv"
}
Tworzenie
Zasób Shortlinks akceptuje następujące parametry przy wykonywaniu zapytania typu POST:
- shortlink[original_link]
- Adres URL, który ma zostać skrócony do wykorzystania z rdir.pl.
Przykładowe użycie
Odczytanie odnośników:
$ curl -v -H'Accept: application/json' -H'X-Blip-api: 0.02'
http://api.blip.pl/shortlinks/all
* About to connect() to api.blip.pl port 80
* Trying 85.232.236.216... * connected
* Connected to api.blip.pl (85.232.236.216) port 80
> GET /updates/272707/recording HTTP/1.1
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1
OpenSSL/0.9.7l zlib/1.2.3
Host: api.blip.pl
Pragma: no-cache
Accept: application/json
X-Blip-api: 0.02
Utworzenie:
$ curl -v -H'Accept: application/json' -H'X-Blip-api: 0.02'
-u foo:s0p3l
-F "shortlink[original_link]=http://shortlink.example.com/"
http://api.blip.pl/shortlinks
* About to connect() to api.blip.pl port 80
* Trying 85.232.236.216... * connected
* Connected to api.blip.pl (85.232.236.216) port 80
* Server auth using Basic with user 'foo'
> POST /updates HTTP/1.1
Authorization: Basic Zm9vOnMwcDNs==
User-Agent: curl/7.13.1 (powerpc-apple-darwin8.0) libcurl/7.13.1
OpenSSL/0.9.7l zlib/1.2.3
Host: api.blip.pl
Pragma: no-cache
Accept: application/json
X-Blip-api: 0.02
Content-Length: 188
Expect: 100-continue
Content-Type: multipart/form-data;
boundary=----------------------------207e7a1fad9a
HTTP/1.1 200 OK
{"shortcode":"a1b2","created_at":"2009-09-30 10:05:52",
"hit_count":0,"original_link":"http://shortlink.example.com/",
"id":123}
Dashboard
(Wymaga uwierzytelnienia)
Operacje
- GET /dashboard
- Zwraca wiadomości figurujące aktualnie na kokpicie danego użytkownika
- GET /dashboard/since/50
- Zwraca wiadomości które pojawiły się na kokpicie od wiadomości o id równym 50
- GET /users/jack/dashboard
- Zwraca wiadomości obecnie widoczne na kokpicie użytkownika jack. Jeżeli uwierzytelniony użytkownik to jack to zawartość zasobu będzie taka sama jak zasobu /dashboard. Jeżeli uwierzytelniony będzie inny użytkownik to widoczne będą statusy, wiadomości kierowane i powiadomienia użytkownika jack
- GET /users/jack/dashboard/since/50
- Zwraca wiadomości które pojawiły się na kokpicie użytkownika jack od wiadomości o id równym 50. Jeżeli uwierzytelniony użytkownik to jack to zawartość zasobu będzie taka sama jak zasobu /dashboard/since/50. Jeżeli uwierzytelniony będzie inny użytkownik to widoczne będą statusy, wiadomości kierowane i powiadomienia użytkownika jack oraz zawartość zasobu /dashboard/since/50 uwierzytelnionego użytkownika.
Powyższe zasoby pobierane przez API zachowują się analogicznie do zasobów przeglądanych przez WWW.
Reprezentacja JSON
Reprezentacją zasobu Dashboard jest tablica statusów wiadomości wszystkich typów.
Bliposphere
(Nie wymaga uwierzytelnienia)
Operacje
- GET /bliposphere
- Zwraca obecną zawartość bliposfery. Uwaga! w przypadku uwierzytelnienia zapytania zwrócona zawartość bliposfery będzie uwzględniać listę ignorowanych uwierzytelnionego użytkownika.
Reprezentacja JSON
Reprezentacją zasobu Bliposphere jest tablica statusów.
Users
(Nie wymaga uwierzytelnienia)
Operacje
- GET /users/jack
- Zwraca użytkownika jack
Reprezentacja JSON
{
"id": 2,
"login": "wiesiek",
"background_path": "/users/wiesiek/background",
"avatar_path": "/users/wiesiek/avatar",
"current_status_path": "/statuses/12345"
}
Klucz current_status może zawierać także klucze pictures_path, movie_path lub recording_path jeśli do statusu są dołączone załączniki.
Subscriptions
(Wymaga uwierzytelnienia)
Zasób subscriptions reprezentuję relację pomiędzy dwoma użytkownikami - "obserwującym" i "obserwowanym". Fakt ten należy mieć cały czas na uwadze podczas korzystania z wywołań API - niezależnie od tego jaki rodzaj subskrypcji pobieramy, zawsze zwrócony zostanie obiekt zawierający dwóch userów, a także transport poprzez który relacja ta zachodzi (obserwowanie przez kokpit, przez Jabbera itp.). Wobec powyższego, nie ma także bezpośredniej korespondencji np. pomiędzy liczbą osób obserwowanych pokazywanych na blip.pl, a liczbą obiektów zwracanych przez /subscriptions/from - jedna osoba może być obserwowana przez dwa transporty, wtedy zaś otrzymujemy dwa obiekty, z identycznymi kluczami tracked_user i tracking_user, a różnym transport.
Operacje
- GET /subscriptions
- Zwraca wszystkie subskrybcje bieżącego użytkownika
- GET /subscriptions/from
- Zwraca subskrybcje od bieżącego użytkownika do innych użytkowników
- GET /subscriptions/to
- Zwraca subskrybcje od innych użytkowników do bieżącego użytkownika
- GET /users/jack/subscriptions
- Zwraca wszystkie subskrybcje użytkownika jack
- GET /users/jack/subscriptions/from
- Zwraca subskrybcje od użytkownika jack do innych użytkowników
- GET /users/jack/subscriptions/to
- Zwraca subskrybcje od innych użytkowników do użytkownika jack
- DELETE /subscriptions/jack
- Usuwa subskrybcje pomiędzy bieżącym użytkownikiem a użytkownikiem jack
- PUT /subscriptions/jack
- Aktualizuje, lub w razie potrzeby tworzy subskrybcje pomiędzy bieżącym użytkownikiem a użytkownikiem jack
- PUT /users/jack/ignore
- Dodaje użytkownika jack do ignorowanych bieżącego użytkownika
- PUT /users/jack/unignore
- Usuwa użytkownika jack z ignorowanych bieżącego użytkownika
Reprezentacja JSON
{
"tracked_user_path": "/users/foo",
"tracking_user_path": '/users/sztywny/",
"transport": { "id": 5, "name": "gg" }
}
Tworzenie/aktualizowanie
Zasób Subscriptions akceptuje następujące parametry przy wykonywaniu zapytania typu PUT:
- id
- id (liczbowe lub login) użytkownika do którego subskrybcje chcemy utworzyć. Może po prostu zostać zawarte w URL-u, np. robiąc PUT do /subscriptions/wiesiek nie jest konieczne jego dodatkowe ustawianie
- subscription[www]
- Wartość true lub false zaznaczająca czy użytkownik ma być śledzony przez WWW i API tj. kokpit
- subscription[im]
- Wartość true lub false zaznaczająca czy użytkownik ma być śledzony przez komunikator (odnosi skutek jedynie jeśli istnieje konfiguracja komunikatora)
Przykładowe użycie
Zasubskrybowanie użytkownika bar poprzez WWW, ale nie przez komunikator:
$ curl -v -H "Accept: application/json" -H "X-Blip-api: 0.02"
-u "foo:" -X PUT "http://api.blip.pl/subscriptions/bar?
subscription\[www\]=1&subscription\[im\]=0"
* About to connect() to api.blip.pl port 80 (#0)
* Trying 85.232.236.216... connected
* Connected to api.blip.pl (85.232.236.216) port 80 (#0)
* Server auth using Basic with user 'foo'
> PUT /subscriptions/bar?subscription[www]=1&subscription[im]=0 HTTP/1.1
> Authorization: Basic Zm9vOmR1cGEuOA==
> User-Agent: curl/7.17.1 (i486-pc-linux-gnu) libcurl/7.16.2
> Host: localhost
> Accept: application/json
> X-Blip-api: 0.02
>
< HTTP/1.1 200 OK
< Connection: close
< Date: Thu, 13 Dec 2007 16:08:14 GMT
< Set-Cookie: _session_id=30b65e83d42b3893156e061d69d4ab7f; path=/
< Status: 200 OK
< X-Runtime: 1.06279
< ETag: "99914b932bd37a50b983c5e7c90ae93b"
< Cache-Control: private, max-age=0, must-revalidate
< Server: Mongrel 1.0.1
< Content-Type: js; charset=utf-8
< Content-Length: 2
<
* Closing connection #0
{}
Tag Subscriptions
(Wymaga uwierzytelnienia)
Zasób tag subscriptions reprezentuję relację pomiędzy użytkownikiem a tagiem. Fakt ten należy mieć cały czas na uwadze podczas korzystania z wywołań API - niezależnie od tego jaki rodzaj subskrypcji pobieramy, zawsze zwrócony zostanie obiekt zawierający użytkownika i tag, a także opis zachodzącej relacji (ignorowanie lub subskrypcja).
Operacje
- GET /tag_subscriptions
- Zwraca wszystkie relacje pomiędzy aktualnie zalogowanym użytkownikiem i tagami
- GET /tag_subscriptions/subscribed
- Zwraca subskrybcje tagów aktualnie zalogowanego użytkownika
- GET /tag_subscriptions/ignored
- Zwraca ignorowane tagi aktualnie zalogowanego użytkownika
- PUT /tag_subscriptions/subscribe/drogiblipie
- Tworzy subskrypcję taga #drogiblipie dla aktualnie zalogowanego użytkownika (odpowiednik "Chcę otrzymywać wszystkie statusy oznaczone #drogiblipie")
- PUT /tag_subscriptions/ignore/drogiblipie
- Ignorowanie taga #drogiblipie dla aktualnie zalogowanego użytkownika (odpowiednik "Nie chcę otrzymywać żadnych statusów oznaczonych #drogiblipie")
- PUT /tag_subscriptions/tracked/drogiblipie
- Wyłączenie subskrypcji lub ignorowania taga #drogiblipie, w zależności od stanu relacji, dla aktualnie zalogowanego użytkownika (odpowiednik "Chcę otrzymywać statusy oznaczone #drogiblipie wysyłane przez osoby, które obserwuję")
Reprezentacja JSON
{
"user_path": "/users/blip",
"tag_path": "/tags/drogiblipie",
"negative": false
}
Przykładowe użycie
Dodanie tagu #drogiblipie do ignorowanych:
$ curl -v -H "Accept: application/json" -H "X-Blip-API: 0.02"
-u "foo:" -X PUT -d ""
"http://api.blip.pl/tag_subscriptions/ignore/drogiblipie"
* About to connect() to api.blip.pl port 80 (#0)
* Trying 85.232.236.216... connected
* Connected to api.blip.pl (85.232.236.216) port 80 (#0)
* Server auth using Basic with user 'foo'
> PUT /tag_subscriptions/tracked/drogiblipie HTTP/1.1
> Authorization: Basic Zm9vOmR1cGEuOA==
> User-Agent: curl/7.17.1 (i486-pc-linux-gnu) libcurl/7.16.2
> Host: localhost
> Accept: application/json
> X-Blip-API: 0.02
>
< HTTP/1.1 200 OK
< Connection: close
< Date: Thu, 13 Dec 2007 16:08:14 GMT
< Set-Cookie: _session_id=30b65e83d42b3893156e061d69d4ab7f; path=/
< Status: 200 OK
< X-Runtime: 1.06279
< ETag: "99914b932bd37a50b983c5e7c90ae93b"
< Cache-Control: private, max-age=0, must-revalidate
< Server: Mongrel 1.0.1
< Content-Type: js; charset=utf-8
< Content-Length: 2
<
* Closing connection #0
{}
Avatar
(Wymaga uwierzytelnienia przy tworzeniu/usuwaniu)
Operacje
- GET /users/jack/avatar
- Zwraca awatar użytkownika jack
- DELETE /avatar
- Usuwa awatar bieżącego użytkownika
- POST /avatar
- Zmienia awatar bieżącego użytkownika
Reprezentacja JSON
{
"id": 1234,
"url": "http://blip.pl/user_generated/avatars/1234.jpg"
}
Tworzenie
Zasób Avatar akceptuje następujące paremetry przy wykonywaniu zapytania typu POST:
- avatar[file]
- Plik do załadowania
Przykładowe użycie
Załadowanie awatara:
$ curl -v -F "avatar[file]=@avatar.jpg" -H "Accept: application/json"
-H "X-Blip-api: 0.02" -u "foo:s0p3l" -X POST
"http://api.blip.pl/avatar"
* About to connect() to api.blip.pl port 80 (#0)
* Trying 85.232.236.216... connected
* Connected to api.blip.pl (85.232.236.216) port 80 (#0)
* Server auth using Basic with user 'foo'
> POST /avatar HTTP/1.1
> Authorization: Basic Zm9vOmR1cGEuOA==
> User-Agent: curl/7.17.1 (i486-pc-linux-gnu) libcurl/7.16.2
> Host: api.blip.pl
> Accept: application/json
> X-Blip-api: 0.02
> Content-Length: 166115
> Expect: 100-continue
> Content-Type: multipart/form-data; boundary=----------------------------fae37744ca25
>
< HTTP/1.1 201 Created
< Connection: close
< Date: Thu, 13 Dec 2007 14:22:41 GMT
< Set-Cookie: _session_id=2775143d87fda1d12ed31e774dd9b0ef; path=/
< Status: 201 Created
< Location: http://api.blip.pl/users/8209/avatar
< X-Runtime: 9.55353
< Cache-Control: no-cache
< Server: Mongrel 1.0.1
< Content-Type: js; charset=utf-8
< Content-Length: 2
<
* Closing connection #0
{}
Updates / Search
(Wymaga uwierzytelnienia)
Operacje
- GET /updates/search
- Wyszukiwanie wiadomości
Parametry
- query
- Wyszukiwany ciąg znaków
- type
- Rodzaj wyszukiwanych wiadomości, domyślnie wyszukiwanie odbywa się po typach Status i DirectedMessage
- user
- Identyfikator nadawcy wiadomości, dozwolony jest łańcuch tekstowy lub tablica parametrów
- recipient
- Identyfikator odbiorcy wiadomości, dozwolony jest łańcuch tekstowy lub tablica parametrów
- since_id
- Identyfikator najstarszej wiadomości uwzględnianej w wyszukiwaniu
Reprezentacja JSON
{
"id": 1,
"created_at": "2007-10-18 11:27:20",
"transport": { "id": 7, "name": "api" },
"transport_description": "BlipFox",
"body": "foobar http://rdir.pl/jk2hg",
"type": "Status",
"user_path": "/users/frania",
"pictures_path": "/updates/1/pictures",
"recording_path": "/updates/1/recording",
"movie_path": "/updates/12/movie"
}
Przykładowe użycie
$ curl -v -u "foo:s0p3l" -H "Accept: application/json"
-H "X-Blip-API: 0.02" http://api.blip.pl/updates/search?query=blip
Likes
(Wymaga uwierzytelnienia)
Każdy status zawiera ilość polubień likes_count
Aby dodatkowo JSON w odpowiedźi zawierał listę użytkowników lubiących dany status likes_user należy ustawić include na likes_user.
Operacje
Przykładowe użycie
$ curl -v -u "foo:s0p3l" -H "Accept: application/json"
-H "X-Blip-API: 0.02" -F 'include=likes_user' http://api.blip.pl/like/5