Jak uporządkować API i schematy dzięki Apicurio Registry

Wyobraź sobie, że budujesz architekturę mikroserwisową, w której dane przepływają przez Kafkę lub żądania REST. Zgromadziłeś tuzin schematów Avro, kilka specyfikacji OpenAPI i garść plików Protobuf. W pewnym momencie jeden zespół aktualizuje schemat wiadomości, a system drugiego zespołu „pęka", ponieważ nie dowiedział się o zmianach na czas. Brzmi znajomo? Oczywiście możesz przechowywać schematy w Git i kopiować je między projektami, ale szybko zamienia się to w chaos.

Natknąłem się na Apicurio Registry podczas poszukiwania alternatywy dla standardowych rozwiązań do zarządzania kontraktami API. To projekt CNCF na etapie sandbox, który rozwiązuje jeden konkretny problem: zapewnia scentralizowane repozytorium dla Twoich API i schematów.

Po co zawracać sobie głowę, skoro mam Git

Kluczowa funkcja nie polega tylko na „odłożeniu pliku na półkę" — chodzi o to, jak rejestr pracuje z tymi danymi. Apicurio Registry może walidować kompatybilność schematów w locie. Gdy usługa-producent próbuje opublikować nową wersję schematu, rejestr może zablokować aktualizację, jeśli łamie ona wsteczną kompatybilność. Wychwytujesz błąd, zanim nieprawidłowe dane trafią do kolejki wiadomości.

Dodatkowo projekt zajmuje się za Ciebie wersjonowaniem. Każdy schemat ma jasny cykl życia, a konsumenci zawsze wiedzą, której wersji używać.

Co siedzi pod maską i jak to działa

Deweloperzy Apicurio wybrali Quarkusa jako fundament, dzięki czemu narzędzie jest szybkie i lekkie. Ale najciekawsza część to elastyczność w opcjach przechowywania. Wcześniej był osobny binarny plik dla każdej bazy danych, a w wersji 3.0 przeszli na pojedynczy artefakt. Teraz wystarczy ustawić zmienną środowiskową APICURIO_STORAGE_KIND i wybrać spośród następujących opcji:

• SQL — klasyczny wybór. Domyślnie H2 (wygodne do testowania), ale w produkcji lepiej użyć PostgreSQL lub SQL Server.
• KafkaSQL — przechowuje dane bezpośrednio w tematach Kafki. To przydatne, jeśli nie chcesz dodawać osobnej relacyjnej bazy danych do swojej infrastruktury i masz już klaster Kafki.
• GitOps — opcja dla tych, którzy chcą deklaratywnego zarządzania.

Dla użytkowników Kubernetes dostępny jest gotowy operator. Aktualizacje przechodzą przez kanały OLM, więc utrzymanie aktualnej wersji w klastrze nie będzie zbyt bolesne.

Jak to wypróbować

Najszybszy sposób, żeby przyjrzeć się systemowi, to uruchomić gotowy obraz Docker. Ale ważne jest, żeby pamiętać: UI zostało przeniesione do osobnego kontenera.

Aby uruchomić sam serwer:

docker run -it -p 8080:8080 apicurio/apicurio-registry:latest-snapshot

A dla interfejsu:

docker run -it -p 8888:8080 apicurio/apicurio-registry-ui:latest-snapshot

Po tym dashboard zarządzania będzie dostępny pod adresem localhost:8888, a dokumentacja własnego API rejestru pod localhost:8080/apis.

Jeśli chcesz wdrożyć pełną konfigurację z PostgreSQL do właściwego testowania, najłatwiejszy sposób to stworzenie pliku Docker Compose:

services:
  postgres:
    image: postgres
    environment:
      POSTGRES_USER: apicurio-registry
      POSTGRES_PASSWORD: password
  app:
    image: apicurio/apicurio-registry:3.0.0
    ports:
      - 8080:8080
    environment:
      APICURIO_STORAGE_KIND: 'sql'
      APICURIO_STORAGE_SQL_KIND: 'postgresql'
      APICURIO_DATASOURCE_URL: 'jdbc:postgresql://postgres/apicurio-registry'
      APICURIO_DATASOURCE_USERNAME: apicurio-registry
      APICURIO_DATASOURCE_PASSWORD: password

Poziomy budowania dla niecierpliwych

Jeśli zdecydujesz się zagłębić w kod źródłowy i zbudować projekt samodzielnie, projekt oferuje trzy „poziomy" budowania. To oszczędza mnóstwo czasu.

Używając flagi -Dlocal, budujesz tylko rdzeń serwera i Java SDK bez dodatkowych kontroli stylu i generowania Javadoc. Budowanie trwa około 3 minut. Jeśli potrzebujesz pełnego pakietu z Go SDK i operatorami, użyj -Dfull. To świetny przykład dbania o czas contributorów.

Kwestie bezpieczeństwa

Out of the box rejestr nie wymaga autoryzacji, co jest w porządku dla lokalnego developmentu, ale niebezpieczne w sieci korporacyjnej. Narzędzie wspiera integrację z OpenID Connect (OIDC). Możesz połączyć Keycloak lub dowolny inny kompatybilny serwer, przekazując parę zmiennych środowiskowych: QUARKUS_OIDC_AUTH_SERVER_URL i QUARKUS_OIDC_CLIENT_ID. Konfiguracja obejmuje zarówno REST API, jak i interfejs użytkownika.

Podsumowanie: kto powinien się temu przyjrzeć

Apicurio Registry z pewnością przyda się zespołom, które:

1. Aktywnie używają Kafki i zmagają się z utrzymywaniem schematów Avro/Protobuf.
2. Chcą zautomatyzować sprawdzanie kompatybilności API (OpenAPI/AsyncAPI).
3. Szukają lekkiej alternatywy dla Confluent Schema Registry, która nie jest silnie powiązana z jednym ekosystemem.

Projekt wygląda na żywy, dokumentacja (nawet wbudowana dokumentacja API) jest szczegółowa, a przejście na Quarkusa sprawia, że obsługa jest przyjemna. Jeśli Twoje mikroserwisy mają sytuację „wszyscy dla wszystkich" jeśli chodzi o kontrakty — spróbuj poświęcić godzinę i uruchomić ten rejestr. Prawdopodobnie rozwiąże większość Twoich problemów z wersjonowaniem schematów.