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

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

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

wersja strony: 36, ostatnia edycja: 22 Oct 2012 15:53

Edytuj Tagi Historia Pliki Drukuj Narzędzia + Opcje

Blip API

Sztuka konserwacji zasobów

Wstęp

Warunki użytkowania

Blipowe dodatki

Biblioteki

Ogólna struktura API

Flash

Formaty danych

Relacje pomiędzy zasobami

Obsługa metod HTTP

Dodatkowe parametry

Odpowiedzi

Typy wiadomości

Pliki graficzne

Awatary

Zapytanie

Dostępne rozmiary awatarów

Lista zasobów

Updates

Operacje

Reprezentacja JSON

Tworzenie

Przykładowe użycie

Directed Messages

Operacje

Reprezentacja JSON

Tworzenie

Statuses

Operacje

Reprezentacja JSON

Tworzenie

Archives

Operacje

Reprezentacja JSON

Private Messages

Operacje

Reprezentacja JSON

Tworzenie

Notices

Operacje

Tags

Operacje

Movie

Operacje

Przykładowe użycie

Reprezentacja JSON

Recording

Operacje

Przykładowe użycie

Reprezentacja JSON

Pictures

Operacje

Reprezentacja JSON

Przykładowe użycie

Shortlinks

Operacje

Reprezentacja JSON

Tworzenie

Przykładowe użycie

Dashboard

Operacje

Reprezentacja JSON

Bliposphere

Operacje

Reprezentacja JSON

Users

Operacje

Reprezentacja JSON

Subscriptions

Operacje

Reprezentacja JSON

Tworzenie/aktualizowanie

Przykładowe użycie

Tag Subscriptions

Operacje

Reprezentacja JSON

Przykładowe użycie

Avatar

Operacje