Na pewno często pracujesz z REST API, na różne sposoby. Na pewno też tworzysz nowe REST API. Praktycznie każdy projekt w jakimś stopniu z niego korzysta.
Tylko pytanie, jak to robisz?
zwykle wygląda to tak
1⃣ Najpierw pojawia się potrzeba:
Potrzebuję, aby serwis X pobrał z mojego serwisu dane.
2⃣ Następnie trzeba zaimplementować:
Dodaję nowy Controller (lub biorę istniejący) i dodaję nowe mapowanie oraz implementację.
3⃣ Na koniec trzeba powiadomić drugą stronę:
Wysyłam tekstowy opis nowego API z kilkoma przykładami, w jaki sposób odpytać o dane itp.
No i byłoby choćby nieźle jakby to tak wyglądało, ale…
Niestety zwykle pojawiają się też następne punkty
4⃣ Życzenia: Zmień model danych na xyz…
5⃣ Kolejne życzenia: Dodaj parametr taki i siaki…
6⃣ Pytania: Jak wygląda format tego parametru, a jak wygląda format tamtego…
7⃣ Kolejne pytania: Co oznacza parametr X…
8⃣ itd…
9⃣ itp…
Development się cofa. Musisz zmieniać implementację, przepisywać testy, czasem choćby całkowicie zmienić założenia.
Problemem jest to, iż nie pracujesz na specyfikacji, którą obie strony zaakceptowały!
Jak OpenAPI może Ci pomóc?
OpenAPI to standard specyfikacji REST API. Może kojarzysz coś takiego jak Swagger, to on dał początki temu standardowi.
Na początku, wszyscy traktowali Swaggera jako sposób na dokumentowanie API. Pozwalał on automatycznie wygenerować specyfikację, którą później można było podłączyć pod wygodne GUI, przy pomocy którego można było odpytywać usługi i zaznajomić się z API. Co więcej, z tak przygotowanej specyfikacji można było wygenerować też kod klienta w wielu językach!
To wszystko przez cały czas jest dostępne w OpenAPI, ale skrzydła rozwiniesz wtedy, kiedy przejdziesz na drugą stronę mocy i wykorzystasz podejście API First. Czyli najpierw specyfikacja, później kod. W sumie brzmi to dosyć logicznie, co?
Specyfikacja OpenAPI ma spore możliwości
Pozwala na zdefiniowanie:
- Dostępnych endpointów i metod HTTP.
- Modelu danych:
- Zwracanych obiektów.
- Przyjmowanych obiektów.
- Wartości enumów.
- Rodzajów parametrów i ich dozwolonych wartości.
- Listy nagłówków i ich wartości.
- Przykładowych danych.
- Adresów serwerów, na których dostępne jest opisywane API.
- Dokumentacji każdego z powyższych elementów.
Co Ci da API First?
Praca nad specyfikacją najpierw, w oderwaniu od kodu ma sporo zalet.
Nie sugerujesz się technologią i jej “specyfiką”.
Myślisz “jak zbudować dobre API”, a nie jak wystawić dane z aplikacji.
Możesz zderzyć swój pomysł na API z drugą stroną, z klientem Twojej usługi.
Każda zmiana może być gwałtownie wprowadzona, bez potrzeby zmian w kodzie.
Masz gotową dokumentację swojego API.
Nie musisz skupiać się na kodowanie Twojego API, bo możesz je wygenerować ze specyfikacji!
Chyba warto, prawda?
