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?

🧐 Zazwyczaj 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 nawet nieźle jakby to tak wyglądało, ale…

🤯 Niestety zazwyczaj 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 nawet całkowicie zmienić założenia.

Problemem jest to, że 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 nadal 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ć szybko 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?