Tworzenie wewnętrznego katalogu API za pomocą Atlassian Compass
KATIE SILVER
GŁÓWNY MENEDŻER PRODUKTU, ATLASSIAN
Streszczenie dla kierownictwa
Miejsce na podsumowanie
Czas
4 minuty czytania. Konfiguracja Compass zajmuje mniej niż 10 minut.
Publiczność
Jesteś członkiem zespołu dostarczającego oprogramowanie i korzystasz z interfejsów API. Te informacje mogą być przydatne dla programistów, inżynierów i innych osób.
Wymagania wstępne
- Zacznij korzystać z Compass — możesz wypróbować ten system za darmo, a rozpoczęcie pracy zajmuje kilka minut.
Stworzenie dokładnego katalogu interfejsów API to trudne zadanie
W ciągu ostatniej dekady duże monolityczne systemy zostały zastąpione przez mikrousługi, architektury rozproszone oraz autonomiczne zespoły. Korzyści są rzeczywiste — podobnie jak konsekwencje. Kompilatory oparte na typach i testy zapewniały dawniej płynną współpracę wszystkich części dużej bazy kodu. Dziś granice wyznaczają interfejsy API i nie ma pewności, czy po wdrożeniu wszystkie będą do siebie pasować.
Wiemy, że programiści działają szybciej, a zespoły dostarczają lepsze produkty, gdy wszyscy rozumieją, jak działają interfejsy API i kiedy się zmieniają. Trudnością jest jednak śledzenie i utrzymywanie tej dokumentacji.
Każda organizacja znajduje się na innym etapie dojrzałości w zakresie mapowania swoich usług. W niektórych zespołach rozmowy na Slacku wystarczają do zapewnienia spójności działań twórców API i użytkowników tych interfejsów. W innych zespołach sposób działania poszczególnych interfejsów API jest dokumentowany podczas tworzenia usługi, ale później nie jest już aktualizowany. Jeśli dysponujesz dobrymi procesami lub narzędziami, każdy interfejs API jest udokumentowany, a informacje o jego zmianach są automatycznie przekazywane pozostałym interesariuszom.
Niezależnie od tego, na jakim etapie tej drogi jesteś, pomóc może Compass — nowa platforma deweloperska Atlassian.
Scentralizowana dokumentacja API w Compass
Gdzie powinna być przechowywana dokumentacja API w środowisku mikrousług? To, że tworzymy i wdrażamy usługi oddzielnie, nie oznacza, że chcemy, aby każda z nich miała własną wydzieloną stronę z dokumentacją lub plik OpenAPI ukryty w bliżej nieokreślonym miejscu. Zespoły chcą zgromadzić wszystkie te informacje w jednym miejscu i mieć możliwość ich przeszukiwania bez ogromnego wewnętrznego nakładu pracy związanego z budowaniem rejestru API.
Compass umożliwia scentralizowanie całej dokumentacji API w godzinę, a nie w ciągu tygodnia czy kwartału. Nie trzeba ręcznie przesyłać dokumentacji po każdym wprowadzeniu zmian — wystarczy połączyć z Compass swoje repozytorium SCM (Bitbucket, GitHub lub GitLab).
W ciągu kilku minut Compass przeskanuje wszystkie repozytoria w poszukiwaniu plików OpenAPI i opublikuje je w katalogu. Wszystkie interfejsy API używane przez zespoły zostaną od razu centralizowane i będą gotowe do przeszukiwania.
Odkrywanie i integracja z API
Wyobraź sobie, że programista otrzymuje zgłoszenie dotyczące stworzenia nowego procesu zwrotów kosztów. Wie, że musi znaleźć odpowiedni interfejs API do obsługi tej funkcji, ale nie wie, od czego zacząć. W wielu firmach pytałby o to na Slacku i potencjalnie czekał godzinami, aż kolega z drugiego końca świata odpowie na pytanie, którego API użyć. W zespołach korzystających z Compass takie informacje można znaleźć samodzielnie. Programiści mogą wyszukiwać punkty końcowe API i znajdować dokładnie te informacje, których potrzebują, bezpośrednio w Compass w zaledwie kilka sekund. Oznacza to, że programista szukający informacji znajduje je szybciej, a zespół będący właścicielem danego interfejsu API rzadziej musi rozwiązywać problemy dotyczące przerw w pracy.
Powiadomienia o zmianach w API
W świecie mikrousług każda usługa wdrażana jest niezależnie, a czasem wprowadza zmiany, o których konsumenci powinni wiedzieć. Na szczęście Compass nie tylko zna dokumentację interfejsów API, ale też śledzi, jak API się zmienia. Za każdym razem, gdy ktoś z zespołu zatwierdzi pull request aktualizujący dokumentację API, Compass również aktualizuje swoją wersję dokumentacji, dzięki czemu wersja widoczna dla programistów w Compass jest zawsze najbardziej aktualną wersją API.
Historyczne zmiany są widoczne także na stronie dziennika zmian, dzięki czemu można sprawdzić, kiedy wprowadzono istotne modyfikacje:
Gdy programiści mają dostęp do potrzebnej dokumentacji, wdrażanie kodu przebiega szybciej
W niedawnym badaniu Postman dotyczącym programistów API 52% respondentów wskazało, że największym problemem podczas pracy nad API jest brak dokumentacji. Spowalnia to proces programowania, utrudnia wdrażanie nowych inżynierów i zwiększa ryzyko błędów w oprogramowaniu.
Gdyby trzeba było samodzielnie stworzyć własny, wewnętrzny katalog API, byłby to ogromny projekt z wieloma ruchomymi elementami. Wykonaliśmy całą tę pracę za Ciebie — scentralizowane centrum dokumentacji jest na wyciągnięcie ręki.
Zapewnij swojemu zespołowi informacje, których potrzebuje, i obserwuj, jak szybciej dostarcza kod. 🚀