API Blox.pl

From BloxWiki

Strona ta przeznaczona jest dla programistów chcących tworzyć aplikacje, które umożliwiają zarządzanie blogiem w serwisie Blox.pl z pominięciem interfejsu www. Program taki może komunikować się z serwisem Blox.pl bezpośrednio przy pomocy API Blox.pl.

Spis treści 1 Oferowane funkcjonalności 2 Kompatybilność 3 Obsługiwane przez Blox.pl metody z Blogger API 3.1 blogger.newPost 3.2 blogger.editPost 3.3 blogger.getPost 3.4 blogger.getRecentPosts 3.5 blogger.deletePost 3.6 blogger.getUsersBlogs 3.7 blogger.getUserInfo 4 Obsługiwane metody z API MetaWebLog 4.1 metaWeblog.newPost 4.2 metaWeblog.newPostExt 4.3 metaWeblog.editPost 4.4 metaWeblog.editPostExt 4.5 metaWeblog.getPost 4.6 metaWeblog.getRecentPosts 4.7 metaWeblog.getCategories 4.8 metaWeblog.newMediaObject 5 Obsługiwane metody z API Movable Type 5.1 mt.getRecentPostTitles 6 Pozostałe metody 6.1 blox.getEntryTagsForEntry 6.2 blox.setEntryTagsForEntry 6.3 blox.getAllEntryTags 7 Przykładowy kod 8 Przykładowy kod 9 Przykład w PHP: metaWeblog.newPost 10 Zmiany w API

Oferowane funkcjonalności

• pobieranie listy blogów użytkownika
• pobieranie listy ostatnich notek z danego bloga
• tworzenie, edycji i kasowanie notek
• ładowanie plików binarnych

Kompatybilność

API Blox.pl zostało stworzone w oparciu o technologię XML-RPC. Pisząc interfejs wzorowaliśmy się na Blogger API, MetaWeblog API oraz MovableType API, metody API Blox.pl są więc w obu przypadkach z nimi kompatybilne. Z API Blox.pl korzysta między innymi program Bloxer.

Żądania wywołania metod XML-RPC powinny być kierowane na adres URI: http://www.blox.pl/xmlrpc

Obsługiwane przez Blox.pl metody z Blogger API

blogger.newPost

wysyła nową notkę na bloga

parametry wywołania:

• appkey - ignorowany
• blogid - nazwa bloga, do którego będzie wysłana nowa notka, np. dla bloga o adresie xyz.blox.pl będzie to xyz (wycofywane) lub numer bloga pobrany metodą getUsersBlogs (zalecane)
• username - login właściciela/administratora/użytkownika bloga (ale nie czytelnika)
• password - hasło użytkownika
• content - treść notki
• publish - czy wpis ma być opublikowany (true) czy zapisany jako szkic (false)

zwraca identyfikator nowego wpisu lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

blogger.editPost

modyfikuje istniejącą notkę

parametry wywołania:

• appkey - ignorowany
• postid - identyfikator liczbowy modyfikowanej notki
• username - login właściciela/administratora bloga lub autora notki
• password - hasło użytkownika
• content - treść notki
• publish - czy wpis ma być opublikowany (true) czy zapisany jako szkic (false)

zwraca true jeśli notka została pomyślnie zmodyfikowana, false w przeciwnym wypadku lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

blogger.getPost

pobiera notkę z bloga

parametry wywołania:

• appkey - ignorowany
• postid - identyfikator liczbowy notki
• username - login właściciela/administratora bloga lub autora notki
• password - hasło użytkownika

zwraca notkę jako tablicę z wartościami przypisanymi do kluczy:

• content - treść
• userid - login autora
• postid - identyfikator liczbowy notki
• dateCreated - data utworzenia notki

lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

blogger.getRecentPosts

pobiera ostatnio napisane notki

parametry wywołania:

• appkey - ignorowany
• blogid - nazwa bloga (wycofywane) lub identyfikator liczbowy bloga pobrany metodą getUsersBlogs (zalecane)
• username - login właściciela/administratora bloga lub autora notek
• password - hasło użytkownika
• numberOfPosts - liczba ostatnich notek, którą chcemy pobrać

zwraca listę notek jako listę tablic z wartościami przypisanymi do kluczy:

• content - treść
• userid - login autora
• postid - identyfikator liczbowy notki
• dateCreated - data utworzenia notki

lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

blogger.deletePost

kasuje notkę

parametry wywołania:

• appkey - ignorowany
• postid - identyfikator liczbowy notki
• username - login właściciela/administratora bloga lub autora notki
• password - hasło użytkownika
• publish - ignorowane

zwraca true lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

blogger.getUsersBlogs

pobiera adresy blogów użytkownika

parametry wywołania:

• appkey - ignorowany
• username - login właściciela/administratora/użytkownika blogów
• password - hasło użytkownika

zwraca listę adresów jako listę tablic z wartościami przypisanymi do kluczy:

• blogid - identyfikator bloga
• url - adres url bloga
• blogName - nazwa bloga

lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

blogger.getUserInfo

zwraca informacje o użytkowniku, częściowo zaimplementowana

parametry wywołania:

• appkey - ignorowany
• username - login każdego użytkownika bloga
• password - hasło użytkownika

zwraca tablicę z wartością przypisaną do klucza:

• userid - login

lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

Obsługiwane metody z API MetaWebLog

metaWeblog.newPost

dodaje nową notkę

parametry wywołania:

• blogid - nazwa bloga (wycofywane) lub identyfikator liczbowy bloga pobrany metodą getUsersBlogs (zalecane)
• username - login właściciela/administratora/użytkownika bloga (ale nie czytelnika)
• password - hasło użytkownika
• content - treść notki jako tablica z wartościami przypisanymi do kluczy:
  • flNotOnHomePage - ignorowany
  • title - tytuł notki (max 255 znaków)
  • lead - wstęp do notki (max 2500 znaków)
  • description - treść notki (max 16KB)
  • categories - lista nazw kategorii, do których ma zostać dodana notka (obecnie obsługiwana tylko 1 kategoria), lub brak wartości - wtedy notka trafia do kategorii domyślnej
  • pubDate - ignorowany, zawsze ustawiana jest bieżąca data
  • guid - ignorowany
  • author - ignorowany, autorem jest zawsze użytkownik podany w username
• publish - czy wpis ma być opublikowany (true) czy zapisany jako szkic (false)

zwraca identyfikator nowo utworzonej notki lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

metaWeblog.newPostExt

Wersja metody metaWeblog.newPost, która ma identyczne parametry wejściowe z newPost, natomiast zwraca tablicę z wartościami przypisanymi do kluczy:

• entryId - identyfikator liczbowy wpisu
• entryUrl - URL wpisu w przypadku jeżeli notka została opublikowana. Jeśli wpis nie został opublikowany wartość nie jest zwracana.

metaWeblog.editPost

modyfikuje notkę

parametry wywołania:

• postid - identyfikator notki
• username - login właściciela/administratora bloga lub autora notki
• password - hasło użytkownika
• content - treść notki jako tablica z wartościami przypisanymi do kluczy:
  • flNotOnHomePage - ignorowany
  • title - tytuł notki (max 255 znaków)
  • lead - wstęp do notki (max 2500 znaków)
  • description - treść notki (max 16KB)
  • categories - lista nazw kategorii, do których ma zostać dodana notka (obecnie obsługiwana tylko 1 kategoria), lub brak wartości - wtedy notka trafia do kategorii domyślnej
  • pubDate - ignorowany, zawsze ustawiana jest bieżąca data
  • guid - ignorowany
  • author - ignorowany, autorem jest zawsze użytkownik podany w username
• publish - czy wpis ma być opublikowany (true) czy zapisany jako szkic (false)

zwraca true lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

metaWeblog.editPostExt

Wersja metody metaWeblog.editPost, która ma identyczne parametry wejściowe z editPost, natomiast zwraca tablicę z wartościami przypisanymi do kluczy:

• entryId - identyfikator liczbowy wpisu
• entryUrl - URL wpisu w przypadku jeżeli notka została opublikowana. Jeśli wpis nie został opublikowany wartość nie jest zwracana.

metaWeblog.getPost

pobiera notkę

parametry wywołania:

• postid - identyfikator notki
• username - login właściciela/administratora bloga lub autora notki
• password - hasło użytkownika

zwraca tablicę z wartościami przypisanymi do kluczy:

• title - tytuł notki
• lead - wstęp do notki
• description - treść notki
• categories - wektor nazw kategorii do których ma zostać dodana notka (obecnie obsługiwana tylko 1 kategoria), lub brak wartości
• pubDate - data publikacji
• guid - identyfikator notki
• author - login autora notki
• entryUrl - URL wpisu, gdy został opublikowany.

lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

metaWeblog.getRecentPosts

pobiera ostatnio napisane notki

parametry wywołania:

• blogid - nazwa bloga (wycofywane) lub identyfikator liczbowy bloga pobrany metodą getUsersBlogs (zalecane)
• username - login właściciela/administratora bloga lub autora notek
• password - hasło użytkownika
• numberOfPosts - liczba ostatnich notek, którą chcemy pobrać

zwraca listę notek jako listę tablic z wartościami przypisanymi do kluczy:

• title - tytuł notki
• description - treść notki
• categories - wektor nazw kategorii do których ma zostać dodana notka (obecnie obsługiwana tylko 1 kategoria), lub brak wartości
• pubDate - data publikacji
• guid - identyfikator notki
• author - login autora notki

lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

metaWeblog.getCategories

pobiera wszystkie kategorie bloga

parametry wywołania:

• blogid - nazwa bloga (wycofywane) lub identyfikator liczbowy bloga pobrany metodą getUsersBlogs (zalecane)
• username - login właściciela/administratora bloga lub autora notek
• password - hasło użytkownika

zwraca listę kategorii jako listę tablic z wartościami przypisanymi do kluczy:

• htmlUrl - nazwa kategorii
• description - opis kategorii

lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

metaWeblog.newMediaObject

ładuje do zasobów bloga nowy plik

parametry wywołania:

• blogid - nazwa bloga (wycofywane) lub identyfikator liczbowy bloga pobrany metodą getUsersBlogs (zalecane)
• username - login użytkownika bloga
• password - hasło użytkownika
• file - plik jako tablica z wartościami przypisanymi do kluczy:
  • name - nazwa pliku
  • type - typ MIME (musi być dozwolony do ładowania na Blox.pl)
  • bits - zawartość pliku formie binarnej

zwraca tablicę z wartościami przypisanymi do kluczy:

• url - adres url załadowanego pliku

lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC.

Obsługiwane metody z API Movable Type

mt.getRecentPostTitles

zwraca listę tytułów notek

parametry wywołania:

• blogid - nazwa bloga (wycofywane) lub identyfikator liczbowy bloga pobrany metodą getUsersBlogs (zalecane)
• username - login właściciela/administratora/użytkownika bloga (ale nie czytelnika)
• password - hasło użytkownika
• numberOfPosts - liczba notek, które serwer ma zwrócić, w kolejności od ostatnio dodanej. Dla wartości -1 zostaną zwrócone tytuły wszystkich notek bloga.

zwraca listę notek jako listę tablic z wartościami przypisanymi do kluczy:

• dateCreated - data utworzenia notki
• userid - login autora
• postid - identyfikator liczbowy notki
• title - tytuł notki

lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

Pozostałe metody

blox.getEntryTagsForEntry

zwraca listę tagów przypisanych do danej notki

parametry wywołania:

• postid - identyfikator liczbowy notki
• username - login właściciela/administratora/użytkownika bloga (ale nie czytelnika)
• password - hasło użytkownika

zwraca listę nazw tagów (wektor) lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

blox.setEntryTagsForEntry

Przypisuje listę tagów do danej notki

parametry wywołania:

• tags - lista nazw tagów, które moją zostać dodane do notki
• postid - identyfikator liczbowy notki
• username - login właściciela/administratora/użytkownika bloga (ale nie czytelnika)
• password - hasło użytkownika

zwraca listę nazw tagów (wektor) zapisanych na serwerze lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC. Lista tagów zapisanych na serwerze może się różnić od listy tagów wysłanych do serwera. Błędy walidacji dotyczą przekroczenia maksymalnej liczby tagów, które moga być przypisane do notki (7), przekroczenia maksymalnej liczby tagów na blog (250) lub użycia tagu zmoderowanego przez administrację serwisu.

blox.getAllEntryTags

zwraca listę wszystkich tagów używanych w danym blogu

parametry wywołania:

• blogid - identyfikator liczbowy bloga
• username - login właściciela/administratora/użytkownika bloga (ale nie czytelnika)
• password - hasło użytkownika

zwraca listę nazw tagów (wektor) lub błąd wywołania procedury zgodny ze specyfikacją XML-RPC

Przykładowy kod

Przykładowy fragent kodu w języku Java, prezentujący sposób użycia metody blogger.getUsersBlogs (wymagany jest pakiet Apache XML-RPC):

 import java.io.IOException;
 import java.net.MalformedURLException;
 import java.util.Hashtable;
 import java.util.Iterator;
 import java.util.Vector;
 import org.apache.xmlrpc.XmlRpcClient;
 import org.apache.xmlrpc.XmlRpcException;
 
 ...
 
 try
 {
   XmlRpcClient client = new XmlRpcClient( "http://www.blox.pl/xmlrpc" );
 	
   Vector params = new Vector();
   params.addElement( "" );
   params.addElement( "twoj_login" ); // username
   params.addElement( "XXXXX" );      // haslo
 
   Vector blogi = (Vector) client.execute( "blogger.getUsersBlogs", params );
 
   if (blogi != null && !blogi.isEmpty())
   {
     for (Iterator i=blogi.iterator(); i.hasNext(); )
     {
       Hashtable blog = (Hashtable) i.next(); 
       System.out.println(blog.get("blogid")+", "+blog.get("url")+", "+blog.get("blogName"));
     }
   }
 } catch (MalformedURLException e) {
   e.printStackTrace();
 } catch (XmlRpcException e) {
   e.printStackTrace();
 } catch (IOException e) {
   e.printStackTrace();
 }
 

Przykładowy kod

Przykład wysłania zapytania do XMLRPC przy użyciu cURL (Client URL) z lini poleceń:

# curl -H "text/xml" --data-binary @/plik.xml http://www.blox.pl/xmlrpc

Przykład w PHP: metaWeblog.newPost

RPC.php możemy wziąć z paczki PEAR/XML_RPC

require_once("RPC.php");
$post_payload['title']=new XML_RPC_Value($title, 'string');
$post_payload['description']=new XML_RPC_Value(stripslashes($post), 'string');
$params = array( new XML_RPC_Value($blog_id, 'string'),
                 new XML_RPC_Value($this->login, 'string'),
                 new XML_RPC_Value($this->password, 'string'),
                 new XML_RPC_Value($post_payload, 'struct'),
                 new XML_RPC_Value('1','boolean')
                 );
$msg = new XML_RPC_Message('metaWeblog.newPost', $params);
$msg->setSendEncoding('ISO-8859-2'); //fix dla krzaczkow;)
$cli = new XML_RPC_Client('/xmlrpc', 'blox.pl');
$resp = $cli->send($msg);
if(!$resp) {
     echo 'communication error <strong>' . $cli->errstr ."</strong>";
     exit;
}

if(!$resp->faultCode()) {
     $val = $resp->value();
     $data = XML_RPC_decode($val);
     if($data > 0) {
          echo 'post id: ' . $data;
     }else{
          echo 'fatal error;)';
     }
}else{
     echo 'Fault Code: ' . $resp->faultCode() . "<br/>";
     echo 'Fault Reason: ' . $resp->faultString() . "<br/>";
}

Powyższy kod został znaleziony w internecie (google <3) i lekko poprawiony do realiów blox.pl, pytania kierować pod michal86@gmail.com

Zmiany w API

12.01.2010 - do metod metaWeblog.newPost, metaWeblog.editPost oraz metaWeblog.newPost została dodana obsługa pola "lead".

31.03.2010 - dodanie metod umożliwiających edycję tagów do notek.

30.04.2010 - dodanie metod metaWeblog.newPost, metaWeblog.editPostExt, dodanie zwracania urla wpisu w metaWeblog.getPost.