[PySilesia] RESTful API

[Marcin Nowak]

Cześć.

Zagadnienia, które mnie interesują w temacie RESTful API, są głównie
związane z budowaniem usług w architekturze HATEOAS.

Większość REST API, z którymi się spotykam, można określić co najwyżej
mianem "RESTish", ale na pewno nie RESTful. Jeśli odkrywamy już, że mamy do
czynienia z RESTish, można zakładać że twórca(-y) dążą do RESTful i to jest
samo w sobie godne wyróżnienia. W pozostałych przypadkach mamy do czynienia
z niewiedzą albo "kłamstwem" (prym w tzw. "marketing bullshicie" wiedzie
chyba ElasticSearch), a prawdziwą plagą jest CRUD vel PUT-GET-POST-DELETE.
Podczas pisania tego maila trafiłem na ciekawą prezentację Bartka
Anrzejczaka, do której się nieco odniosę:
http://bandrzejczak.com/hateoas-presentation/

Wg mnie najważniejsze aspekty związane z HATEOAS:

   - reprezentacje (stanu) i metaopis zasobów (w tym opis powiązań między
   nimi)
   - modyfikowanie stanu
   - wersjonowanie API (a raczej reprezentacji)
   - content negotiation
   - hypermedia dla JSON (JSON-LD, HAL, etc)
   - dokumentacja (albo właściwie brak konieczności jej sporządzania)
   - budowanie klienta RESTful i określenie czym właściwie jest "klient",
   unikanie kontraktów
   - RFC7231
   - Roy Fielding

Ale Bartek celnie punktuje też wady HATEOAS:

   - Więcej pracy
   - Więcej transferu
   - Brak ekspertów w temacie
   - Tworzenie API dla nieistniejącego klienta

Więcej pracy - sprawa jest prosta, bo to oznacza "drożej", a klient
biznesowy nie chce API tylko produktu / feature.

Więcej transferu - z powodu szerszego metaopisu (i w ogóle tworzenia
metaopisu) oraz nieznanych klientów. Transfer można ograniczać różnymi
rodzajami reprezentacji (zob. RFC 6.4.1 - status "300") i jakąś
samodecyzyjnością klienta RESTful.

Brak ekspertów w temacie - to widoczne gołym okiem, szczególnie w postaci
zalanej sieci bełkotem (tzw. tutorialami) na temat REST-a. Cennej wiedzy
jest niewiele.

I w końcu "tworzenie dla nie istniejącego klienta". Z tego powodu często
upraszczamy nasze API umawiając się na pewien kontrakt opisany jako IDL,
szeroko w dokumentacji albo co gorsza - nijak nie opisany, tylko
oprogramowany ad-hoc po stronie klienta i serwera i to dla ściśle opisanych
przypadków użycia. I to nie jest REST(ful) API, ani nawet RESTish i w
takich przypadkach nawet warto rozważać RPC typu JSON-RPC ze względu na
ściśle określony protokół i mnogość implementacji bibliotek.

Moją intencją jest:

   - pogłębianie i propagowane wiedzy na temat budowy RESTful API w
   architekturze HATEOAS (bo tylko taka definiuje RESTful), stąd mój post
   (jakoś zacząć trzeba)
   - dobór narzędzi po stronie serwerowej (najczęściej Python) oraz
   klienckiej (najczęściej EcmaScript/JavaScript)
   - wypracowanie stylu programowania RESTful services (już ściśle związane
   z narzędziem)
   - zachęcenie społeczności do rozwoju takiego narzędzia dla Pythona -
   http://restosaur.readthedocs.io/en/latest/
   - być może ujęcie tej całej wiedzy w jakiejś spójnej formie i oczywiście
   opublikowanie jej
   - opracować instruktaż dla każdego "jak przejść na RESTish", jako krok
   ku podniesieniu jakości budowanych usług i (tak na prawdę) ułatwieniu sobie
   życia.

Wiedzę na temat RESTful API poszerzam stale od kilku lat. Zagadnień jest
już tyle, że staje się trudne ogarnąć je bez zapisywania. Wątpliwości jest
równie niemało i wymagają dyskusji.

Na przestrzeni tych kilku lat wypracowałem metodę tworzenia "RESTish" na
jakimś sensownym poziomie (tak mi się przynajmniej zdaje) przy względnie
niskim nakładzie pracy. Chętnie bym ją przedstawił, przedyskutował, ale
niekoniecznie jeszcze opisywał.


Marcin Nowak
-------------- następna część ---------
Załącznik HTML został usunięty...
URL:  <http://mail.python.org/pipermail/pysilesia/attachments/20161012/49953892/attachment-0001.html>