Twórcy aplikacji | dev.cambler.pl

Cambler API

API / blip 0.02

Interfejs programistyczny (API) serwisu Cambler umożliwia tworzenie aplikacji wykorzystujących zasoby serwisu zewnętrznym aplikacjom. Jest on prawie identyczny z API Blip, z wyjątkiem kilku drobnych różnic, dzięki temu łatwo możesz przenieść aplikacje z Blipa na Camblera.

Wszelkie uwagi i pytania można przesyłać na adres

Struktura

Intefejs programistyczny Cambler.pl do komunikacji korzysta z protokołu HTTP. Niezależnie od stanu nagłówka Accept na typ MIME zwracanego zasobu to application/json, zakodowanw w UTF-8.

Dla zapytań PUT i POST dane przyjmowane są w postaci parametrów zakodowanych w formie danych formularza lub w postaci JSON. Tekst powinien zakodowany w UTF-8.

Identyfikacja aplikacji odbywa się poprzez nagłówek User-Agent: (lub X-Blip-Application:). Nie jest on jednak wymagany. Do przesyłania zapytań do API należy używać poniższego adresu URL:

http://api.cambler.pl/blip0.2/

Relacje

Powiązania zasobami API 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 zasobu powiązanego. Przykładowo np. jeśli wpis zawiera obraz, to w jego zasobie występuje klucz pictures_path identyfikujący JSON reprezentujący obrazek. Niekiedy reprezentacja jednego zasobu jest zagnieżdżana w drugim - np. JSON statusu zawiera klucz user, z adresem URL zasobu autora wpisu.

Obsługa metod HTTP

W niektórych przypadkach różne operacje dostępne są pod tym samym URL, a rodzaj żądania jest rozpoznawany na postawie nagłówka HTTP. Zgodnie ze specyfikacją REST, żądanie typu POST odpowiada tworzeniu nowego obiektu, PUT jego uaktualnieniu, DELETE usunięciu, a GET pobraniu zasobu.

Możliwe jest też wykonanie zapytania POST z polem _method zawierającym nazwę żadania HTTP - jest to rozwiązanie niezbędne m. in. do komunikacji z Flashem, który nie obsługuje innych niż GET i POST.

Dodatkowe parametry

Parametr include powoduje umieszczenie reprezentacji zasobów powiązanych bezpośrednio w reprezentacji pobranego zasobu, zamiast klucza z końcówką _path. 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 języka JavaScript, pomocne są także opcjonalne parametry variable (przypisanie do zmiennej) i callback (wykonanie funckcji z argumentem). Można używać obu tych zmiennych naraz, co skutkuje przypisaniem danych do zmiennej variable, po czym wykonanie funkcji callback z danymi jako argumentem. Aby otrzymać w swojej aplikacji dane, należy:

1. Dołączyć rozszerzenie ".json" do urla akcji, w zastępstwie nagłówka Accept np. wywołanie http://api.cambler.pl/updates?limit=20 zastąpić http://api.cambler.pl/updates.json?limit=20
2. Wstawić do dokumentu HTML tag <script>, odwołujący się do URL odpowiedniej akcji API, wraz z parametrami callback / variable.

Ustawienie paremetru callback lub variable, skutkuje inną formą odpowiedzi - wszędzie dostajemy 200 OK i callback / variable na pustą tablicę.