# Potrzebujemy lepszego RESTa

Source: https://apigenie.pl/blog/we-need-better-rest-pl

## O czym jest ten artykuł ?

W tym artykule opowiem, dlaczego stworzyłem projekt API Genie, oraz jak
API Genie ma usprawnić proces tworzenia API REST-owych.

Przez ostatnich 10 lat pracuję z API webowymi. Pracowałem z GraphQL, RPC,
SOAP-em itd., ale większość z nich była oparta o podejście REST.

Powiem szczerze: choć podoba mi się większość założeń podejścia REST, od kilku
lat mam przekonanie, że rozwój owego podejścia zatrzymał się. Typowe problemy
deweloperów tworzących API RESTowe nie zmieniają się od dawna, a odpowiedzi na
większość z nich to cały czas “oto trzy alternatywy (wersjonowania), ale żadna
nie rozwiązuje problemu w całości” albo “wiem, że to (agregowanie różnych
zasobów w jednej końcówce) jest pragmatyczne, ale nie jest to zgodne z czystym
RESTem”. Przy czym nikt owego “czystego RESTa” na żywo nie widział !

Stąd narodził się pomysł na stworzenie projektu API Genie.

W zamyśle API Genie ma:

- łączyć to dobre co ma REST (jest tego całkiem sporo) z dobrymi praktykami z
  innych obszarów, które jeszcze nie zostały zaadoptowane
- dostarczać narzędzi o najwyższym developer experience do wspomagania procesów
  projektowania oraz rozwoju API RESTowych
- tworzyć bazę wiedzy o najlepszych praktykach projektowania API

## Co jest nie tak z REST-em ?

W istocie, nic. Są natomiast kilka aspektów tego podejścia które nie zostały
dobrze zrozumiane.

Po pierwsze, **REST nie jest specyfikacją, tylko podejściem
architektonicznym**. Innymi słowy, zbiorem dość ogólnych zasad określających,
jak należy tworzyć systemy rozproszone. Nie dostarcza żadnej formalnej
specyfikacji, ani wytycznych, ani oprogramowania, które by wspomagało to
podejście w codziennej pracy.

O ile te braki nie są problemem dla doświadczonych programistów (zawsze mogą
wymyślić i poustawiać brakujące klocki, tak żeby pasowały do konkretnej
sytuacji), to powodują sporo pytań ze strony młodszych kolegów. Poza tym, na
pytania każdy może odpowiedzieć trochę inaczej, a to rodzi niezrozumienie ("w
poprzednim projekcie robiliśmy inaczej", albo "mi tamto podejście bardziej się
podoba") oraz sprowadza dyskusje techniczne na poziom emocjonalny. A to już
osłabiają zaufanie do samej technologii.

Po drugie, **część założeń RESTa dot. API, są dla większości z nas
nieistotne**. Roy Fielding (twórca koncepcji REST) pisał, że REST opisuje
sposób tworzenia systemów rozproszonych które powinny ewoluować przez
dziesieciolecia. Żeby umożliwić ewolucje systemów o tej skali, należałoby je
odizolować (ang. decouple) od swoich klientów. Ponieważ w tamtych czasach nie
było wtedy prostego sposobu do opisania kontraktów, postulował iż API RESTowe
powinny być sterowalnymi przez przez klientów (be hypermedia driven). W
praktyce to oznacza, ze:

- oprócz danych, API powinny przekazywać całą masę metainformacji o tych danych
- klienty powinny te meta informacje "rozumieć”

Założenia te owszem są słuszne, tyle ze znacząco komplikują tworzenie oraz
użycie REST API. A najważniejsze - zdecydowana większość developerów tego nie
potrzebuje !

Potrzebuje natomiast innych cech:

- łatwości w tworzeniu oraz rozwoju
- łatwości wprowadzania zmian
- łatwości w użyciu

Po trzecie, **sztywna postawa Roy Fielding-a**, który zacięcie bronił
znaczenia skrótu REST. Według niego, API, które nie jest sterowane przez
metadane (ang. - hypermedia-driven), nie jest RESTowe. Takie zerojedynkowe
podejście powodowało niezrozumienie wśród deweloperów. To co my w końcu
tworzymy - REST, czy jeszcze nie ? A jeśli nie, to jak go nazwać ? Tak trwało
do momentu, w którym Leonard Richardson zaproponował model dojrzałości REST.
Od tamtego czasu, używając skrótu RESTful, poniekąd udajemy że to jest "prawie
REST", ale cały czas nikt nie tworzy RESTowych API, które by były zgodne z
oryginalną definicją.

## No dobra, a co dobrego ?

Idea REST ma w sobie kilka bardzo pożytecznych założeń:

Pierwsze to **skupianie się na zasobach oraz ich stanie**. Zasób to odpowiednik
obiektu lub encji, czyli czegoś, co ma swoją nazwę i ma sens w kontekście
pewnej dziedziny. Podejście oparte na zasobach jest bardzo praktyczne,
ponieważ w każdym, dosłownie każdym podejściu do projektowania musisz nazywać
“cośki”, których używasz.

Owszem, REST dużo większą wagę przydziela stanowi zasobów aniżeli operacjom
nad nimi. Zasadniczo mamy w REST 4 bardzo generyczne operacji, które skrótowo
nazywamy CRUDem. Czasami taka generyczność nieco utrudnia pracę projektantów,
szczególnie w podejściach jak np. DDD, które skupiają się na operacjach tak
samo mocno jak na samych encjach. Omówię ten problem oraz jego rozwiązanie w
kolejnych artykułach.

Drugie założenie (a nawet cała grupa) to **używanie istniejącej infrastruktury
WWW**. Pomijając temat hyper mediów, serwery REST API są trywialne do
stworzenia w dowolnym frameworku webowym. A to dlatego, że REST opiera się o
infrastrukturę WWW . Używanie URL-i do identyfikacji zasobów - przecież to ten
sam protokół, który stosujemy w przypadku stron internetowych. Używanie
jednorodnego interfejsu do reprezentowania operacji nad zasobami ? A proszę
bardzo, mamy metody HTTP oraz formularze HTTP, które z powodzeniem
wykorzystują część tych metod. Cacheowanie ? Monitoring ? Oto masz gotowe
oprogramowanie które to robi bardzo wydajnie.

## API Genie i jego misja

API Genie ma na celu zmodernizowanie podejścia w którym tworzymy API oparte o
zasoby (odmianą którego jest REST). Project ma trzy (równie ważne) cele:

- połączyć to, co dobre w podejściu REST, z większym pragmatyzmem, oraz z
  dobrymi praktykami z innych obszarów;
- dostarczyć narzędzi o najlepszym developer experience do wspomagania procesów
  projektowania oraz rozwoju API;
- stworzyć bazę wiedzy o najlepszych praktykach projektowania API, razem z
  konkretnymi przykładami z różnych dziedzin;

A oto zasady którymi będę kierował się.

**Na każde pytanie powinna być jedna jasna odpowiedź**. Oprócz narzędzi
API Genie ma na celu zebranie bazy wiedzy o dobrych praktykach oraz typowe
przykłady API z różnych branż.

**Opieramy się o pojęcie zasobów**. Tutaj niczym nie różnimy się od REST.
Zasób (ang. - resource) jest czymś co ma nazwę oraz tożsamość. `Employee`,
`Credit` albo `Onboarding` może być zasobem.

**Do identyfikacji zasobów używamy URLi**. Podobnie jak wyżej, zdecydowana
większość zasobów jest identyfikowana za pomocą URLi. Jeśli któryś zasób
występuje tylko i wyłącznie jako składowa innuch zasobów, może nie mieć
dedykowanego URLa.

**Używamy metod HTTP do reprezentowania operacji na zasobach**. To jest
ostatnia zasada zapożyczona z REST. Używanie standardowych metod HTTP pozwala
na pełne wykorzystywanie semantyki oraz infrastruktury WWW oraz sparcia
framework-ów.

**Źródłem prawdy o API jest schema**. Schema jest formalnym opisem API, który
pozwala na oddzielenie kontraktu od implementacji. Posiadanie formalnej schemy
daje wiele zalet, umożliwiając m.in. :

- projektowanie API bez zagłębienia się w szczegóły implementacji. To pozwala
  skupić się na funkcjonalności API; również upraszcza wspieranie kilku
  technologie wewnątrz organizacji
- angażowanie większych grup developerów od samego początku, co pozwala na
  lepszy i wcześniejszy feedback
- wcześniejszą integrację z API od strony użytkowników
- najważniejsze - posiadanie jednej schemy, agnostycznej w stosunku do
  technologii, odblokowuje możliwość generowania kodu

**Kod jest pochodną schemy, i w większości powinien być generowany**. Innymi
słowy, jeśli kod może być wygenerowany na podstawie schemy, powinien zostać
wygenerowany.

Generowanie ma wiele zalet, m.in.:

- zmieniamy generatory dużo rzadziej niż ich wywołujemy, a więc ostatecznie
  oszczędzamy czas i wysiłek
- wygenerowany kod jest spójny oraz zgodny z normami przyjętymi w organizacji
- globalne zmiany, jak np. migracje, są trywialne
- utrzymanie spójności pomiędzy różnymi artefaktami (np. między dokumentacją a
  kodem) jest trywialna

Owszem, stworzenie generatorów jest bardziej skomplikowanym zadaniem niż
napisanie kontrolera RESTowego. Na szczęście ta dziedzina została dobrze
opracowana, a sposób generowania kodu jest podobny dla większości śtechnologii.

**Podejście do tworzenia API powinno być pragmatyczne, nie pedantyczne**.
API Genie ma rozwiązywać rzeczywiste problemy deweloperów. O ile trzymanie się
zasad jest na ogół dobre, czasami należy robić odstępstwa. Owszem, należy je
robić świadomie, ze zrozumieniem wpływu na pożądane cechy API, jak np.
przystępność czy wydajność. No i należy pamiętać że wyjątki powinny być
stosunkowo rzadkie (powiedzmy, 2% przypadków), żeby zostawać wyjątkami.

**Należy utrzymywać kompatybilność z istniejącymi technologiami**. Jestem tego
zdania iż należy korzystać z doświadczenia poprzedników, a swój wysiłek
aplikować na co już zostało zrobione. W taki sposób unikniemy wynalezienia koła
na nowo oraz ogólnie przyśpieszymy postęp.

Narzędzia API Genie będą kompatybilne ze standardem OpenAPI 3.x oraz nowszymi.
I tak zostanie. Aczkolwiek nie wykluczam dodania wsparcia innych standardów
opisu.

**Narzędzia powinny wspierać developerów w każdej czynności**. W praktyce to
oznacza iż narzędzia będą zintegrowane z edytorami, IDE oraz przeglądarkami
(jako najczęściej używanymi klientami API). Powinny one być tak przystępne jak
szczoteczka do zębów.

**Należy umożliwiać stopniową adopcję podejścia schema first**. Migracja z
podejścia schema-less (jako najczęściej stosowanego obecnie) do podejścia
schema driven może wymaga sporo czasu. Dlatego narzędzia API Genie będą
umożliwiały stopniową migrację, tak żeby wdrożenie było przyjemniejsze.

## I co teraz ?

Teraz do roboty.
