REST API (BETA)

[Daniel Macyszyn]

Witam

Dodaliśmy do Sejmometru REST API. Narazie nie podajemy informacji o tym na stronie, bo chciałem Was poprosić o opinię, co do samej filozofii działania. Oto jak to działa:

Pod adresy URL Sejmometru, pod którymi wyświetlane są strony HTML, można wysyłać żądania HTTP z odpowiednimi nagłówkami Accept. W tej chwili akceptowane są dwie wartości:
application/vnd.EPF_API.v1+xml (jeśli chcemy otrzymać dane w XML),
application/vnd.EPF_API.v1+json (jeśli chcemy otrzymać dane w JSON),
(dla każdej innej wartości, serwer zwróci stronę HTML).

Oto przykład w PHP:
   
    $opts = array(
      'http'=>array(
        'method' => "GET",
        'header' => array("Accept: application/vnd.EPF_API.v1+xml"),
      ),
    );
   
    $context = stream_context_create( $opts );
    $url = 'http://sejmometr.pl/gminy';
   
    $transport = file_get_contents( $url, null, $context );
    var_dump( $transport );


Odpowiedź z REST API jest dokumentem, z określonym polem "resource". To pole może być równe "ep_Dataset" lub "ep_Object".


Przykład 1
Jeśli chcemy przeglądać zbiór aktów prawnych, to należy wysyłać żądania pod adres:
http://sejmometr.pl/prawo

W odpowiedzi dostaniemy dokument typu "ep_Dataset". Dla zasobów tego typu, możemy dodatkowo kierować parametry GET:
p - numer strony wyników (domyślnie: 1)
pp - liczba wyników na stronę (każdy dataset ma swoją domyślną wartość, najczęściej 20)
w - pozwala filtrować wyniki. musi być tablicą conajmniej 3 elementów: ['nazwa_pola', 'operator', 'wartosc']. Dozwolone operatory: =, <, >, <=, >=, LIKE, 'IN_LAST_MONTHS'
o - pozwala sortować wyniki. musi być tablicą conajmniej 2 elementów: ['nazwa_pola', 'kierunek']. Dozwolone kierunki: ASC, DESC
k - dodatkowy filtr wyników. tablica fraz do szukania w datasecie. Dla większości datasetów miałomto być wyszukiwanie pełnotekstowe. Dla niektórych (np kody pocztowe) jest to wyszukiwanie "proste". ten filtr nie działa obecnie tak jak powinien. pracujemy nad tym.


Przykład 2
Jeżeli znamy id obiektu, którego dane chcemy uzyskać, to należy wysłać odpowiednie żądanie pod adres URL Sejmometru. Np jeśli chcemy uzyskać informacje o gminie, której id=100, to wysyłamy żądanie pod http://sejmometr.pl/gminy/100.

W odpowiedzi dostaniemy zasób typu "ep_Object". Docelowo pod adresy obiektów będzie można wysyłać parametry GET, które umożliwią załadowanie dodatkowych warstw obiektu. Np  w przypadku gmin, dodatkową warstwą może być zbiór punktów będących granicą geodezyjną gminy, wyniki wyborów itp. Pracujemy nad tym?



Proszę o opinię, czy tak może być i czy możemy iść dalej z takim systemem.
W tej chwili REST API jest dostępne bez żadnych ograniczeń. Docelowo chcielibyśmy, aby mogli z niego korzystać tylko osoby, które mają konto w Sejmometrze. Czy OAuth2 będzie dobrym systemem zarządzania dostępem przez tokeny?


Pozdrawiam
Daniel Macyszyn


 

[Rafał Stożek]

Zacznijmy od parametrów. Już ten problem zgłaszałem - GET nie pozwala na przesyłanie skomplikowanych struktur jak zagnieżdżone listy czy tablice asocjacyjne. PHP ma swój mechanizm który to umożliwia, ale w każdym innym języku nie ma łatwego rozwiązania - będzie to wymagało napisania sporego fragmentu kodu.

Co do oauth2 to podstawowe pytanie - oauth2 ma sens w przypadku aplikacji, które wykorzystują dostęp do danych użytkownika (np. aplikacje facebookowe mają dostęp do postów czy zdjęć użytkownika, który się zalogował). Jeżeli takie funkcje nie są potrzebne, to zrobiłbym najprościej jak się da: Basic Auth lub wykorzystać wygenerowany wcześniej token w nagłówku Authorization (coś podobnego do bearer token w  oauth2 - http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-22).

[bartlomi...@moineau.eu]

Częściowo zgadzam się z przedmówcą.

Po co się w ogóle logować? Chcecie sprzedawać dostęp do tych danych? Jeśli nie, to po co to logowanie?

Kolejna sprawa: po co dodawać sortowania, wyszukiwanie pełnotekstowe i inne zaawansowane opcje w REST API? To będzie dodatkowo obciążać serwery. Czy nie lepiej przygotować coś prostszego, bardziej przejrzystego i za to stabilnego? Możnaby łatwo tworzyć mirrory np. z redisem i nginxem...
Takie moje 0.03PLN.

[Marcin Ciunelis]

Cześć, 

Kilka pytań i uwag:

1. czy można w jakiś sposób otrzymać wykini głosowania? http://sejmometr.pl/sejm_glosowania/1998/wyniki i http://sejmometr.pl/poslowie/2/glosowania zwracaja "główny" obiekt.
2. autoryzacja moim zdaniem nie jest potrzebna chyba, ze do statsow lub ograniczenia zapytan. W takim przypadku token w url albo nagłówku.
3. attrubuty zwracanych obiektow moglyby mieć bardziej znaczace nazwy. n, l, p, g, w, wb, z sa malo intuicyjne
4. w posel: zamiast (albo oprocz) atrubutu biuro_html moglby by zagniezdzony atrubut biuro (bez html) albo biuro_id
5. document, content, class, resource, data to wedlug mnie niepotrzebny halas. Przykładowo obiekt glosowanie powienien wygladac tak: https://gist.github.com/martinciu/5008476 (plus layers i links jesli bedzie tam cos uzytecznego)
6. w posel nie ma url zdjecia
7. w posel nie ma twitter_id (ani handle)

[Paweł Sroka]

Autoryzacja jest ok, trzeba obserwować czy ktoś nie przegina z
obciążaniem serwera. Nie jest to wielkie halo, a kontrola jest
uzasadniona.

Pozdrawiam,
--
Paweł Sroka


W dniu 21 lutego 2013 23:09 użytkownik Marcin Ciunelis
<marcin....@gmail.com> napisał:

> --
> Otrzymujesz tę wiadomość, ponieważ subskrybujesz grupę dyskusyjną Google o
> nazwie "Sejmometr API".
>
> Aby anulować subskrypcję tej grupy i przestać otrzymywać z niej wiadomości,
> wyślij e-maila do sejmometr-ap...@googlegroups.com.
> Więcej opcji znajdziesz na https://groups.google.com/groups/opt_out
>
>