Sblam! — dokumentacja API serwera

There is an English version of this document.

To jest dokumentacja API serwera przeznaczona dla twórców wtyczek. Jeśli chcesz dodać filtr do stron napisanych w PHP lub Perl, wystarczy, że skorzystasz z już istniejących wtyczek.

Automatyczne logowanie

Strona statystyk może być otworzona automatycznie za pomocą linku w postaci:

https://sblam.com/key.html?autologin=apikeyhash:time:sig

gdzie:

apikeyhash to hash MD5 (jako hex, 32 znaki) ciągu: „^&$@$2\n” + klucz API + „@@”. \n to znak przejścia do nowej linii (LF).
time to czas w formacie unix timestamp, kiedy link ma stracić ważność (użyj czegoś w rodzaju time()+3600)
sig to hash MD5 ciągu: time + klucz API

Na przykład link dla klucza „abc123abc123” ważny do 13.12.2007 14:19:27 ma mieć wartość autologin:

b7fc0a3373502b96f23c0cae099993d2:1197555567:e65ca523a9c8d687be2ebddbb86869f4

Automatyczne generowanie kluczy API

Pobierz zawartość spod adresu: https://sblam.com/keygen.html

API serwera

Znajomość API serwera jest potrzebna tylko do napisania wtyczki dla innych języków programowania, niż PHP i Perl (dla których są już oficjalne wtyczki).

Serwer używa własnego binarnego API oraz nietypowych nagłówków HTTP. Wtyczka musi mieć możliwość wysłania zapytania HTTP POST w specyficznym formacie (który jest umyślnie niekompatybilny z POST z formularzy).

Dane wysyłane do serwera to pola zapisane w parach klucz-wartość. Klucze i wartości są oddzielane od siebie znakiem NUL (bajt 0) i kodowane w UTF-8. Treść POST wysyłana do serwera wygląda mniej więcej tak:

klucz1\0wartosc1\0klucz2\0wartosc2\0

Informacje o nadawcy

Wymagane pola
Nazwa pola	Opis zawartości
uid	niezmienny identyfikator serwera, który jest niemożliwy do zgadnięcia. To może być dowolny ciąg znaków.
uri	ścieżka, pod którą zostało wysłane zapytanie (np. „`/cgi-bin/form.cgi`”. W CGI to zmienna `REQUEST_URI`)
host	domena serwera (np. „example.com”, w CGI to `HTTP_HOST` lub `SERVER_NAME`)
ip	IP nadawcy postu (jako tekst w formacie „123.123.123.123”)
time	data/czas wysłania postu jako unix timestamp (np. „1187543533”)
cookies	„1” jeśli nadawca postu przyjmuje cookies, „0” jeśli nie
session	„1” jeśli nadawca pobrał niedawno pliki z serwera (rozpoczynając sesję), „0” jeśli od razu wysłał formularz
sblamcookie	zawartość cookie o nazwie „sblam_”
salt	trudny do zgadnięcia, najlepiej niepowtarzalny ciąg znaków

Opcjonalne pola
Nazwa pola	Opis zawartości
field_0	nazwa pola formularza, które zawiera wiadomość (np. „comment”)
field_1	nazwa pola formularza, które zawiera podpis autora (np. „author”)
field_2	nazwa pola formularza, które zawiera adres e-mail autora (np. „e-mail”)
field_3	nazwa pola formularza, które zawiera adres WWW podany przez autora (np. „website”)

Pola field_X mają zawierać nazwy pól formularza, a nie treść. Zamiast nazwy mogą zawierać pusty ciąg, co oznacza, że dane pole nie występuje w formularzu.

Jeśli pola field_X nie zostaną wysłane do serwera, to serwer będzie zgadywał nazwy pól formularza.

W przyszłości serwer będzie przyjmował dodatkowe opcje filtrowania (ustawiane przez użytkownika wtyczki) przekazywane za pomocą pól nazwanych wg schematu field_nazwa, więc ten element implementacji warto mieć elastyczny.

Przekazywanie nadesłanych danych

Należy przekazać do serwera wszystkie pola z formularza przysłane przez użytkownika metodą POST (oczywiście pomijając pola zawierające hasła i inne poufne dane).

Do nazw pól formularza należy dodać przedrostek POST_. Jeśli pole występuje kilkakrotnie, należy wszystkie połączyć w jeden ciąg.

<textarea name="tresc">hello</textarea>

POST_tresc\0hello\0

Podobnie należy przekazać wszystkie nagłówki HTTP (oprócz Cookie i Authorization, które zawierają poufne dane). Ich nazwy powinny być znormalizowane tak samo, jak w skryptach CGI — z predrostkiem HTTP_, dużymi literami i z „-” zamienionym na „_”.

User-Agent: spambot

HTTP_USER_AGENT\0spambot\0

Wysyłanie do serwera

Zapytanie musi być wykonane metodą POST. Musi mieć nagłówek HTTP:

Content-Type:application/x-sblam;sig=XXXYYY

lub

Content-Type:application/x-sblam;sig=XXXYYY;compress=gzip

jeśli dane zostały skompresowane przez gzip.

Gdzie XXX to hash MD5 (jako hex, 32 znaki) ciągu: „^&$@$2\n” + klucz API + „@@”. \n to znak przejścia do nowej linii (LF).

md5("^&$@$2\ndefault@@"); // dla klucza „default”

YYY to hash MD5 ciągu: klucz API + dane (jeśli są skompresowane, to hash z danych po kompresji)

Odpowiedź od serwera

Jeśli serwer odpowie innym statusem, niż 200, to opis błędu będzie w linii statusu HTTP.

Jeśli serwer odpowie statusem 200, to w ciele odpowiedzi będą pola oddzielone dwukropkiem:

-1:2a6d8fa0d:bb9c177510ba9219c75e0e02876c9c96

wynik filtrowania (wyjaśniony w opisie wtyczki PHP)
identyfikator postu do raportowania pomyłki wtyczki (może być pusty lub „0”, co oznacza, że post nie został przyjęty przez serwer). Pomyłki wtyczki użytkownik może raportować pod adresem: https://sblam.com/report/identyfikator postu
hash MD5 ciągu: klucz API + wynik + pole „salt” z wysłanych do serwera danych. Sprawdzenie tego ciągu z twoimi danymi daje gwarancję, że nikt nie podszywa się pod serwer.

Skrypt JavaScript

Bardzo ważny jest też skrypt JavaScript, który potwierdza, że przeglądarka użytkownika obsługuje JavaScript oraz przy okazji mierzy czas pisania postu. Wersja dla PHP dołączona do wtyczki powinna być na tyle prosta, że nie wymaga dokumentacji (większość nieczytelnego kodu w niej to JavaScript, który musi pozostać niezmieniony).