Przejdź na adres API

Wcześniejsze integracje wywołują API pod adresem głównym Sursy, tym, który ludzie otwierają w przeglądarce, np. https://app.sursa.com/v1/…. Teraz API ma też własny adres: https://api.sursa.com w chmurze lub https://api.<your domain> w Twojej instalacji. Ten adres powstał z myślą o integracjach: skaluje się poziomo za modułem równoważenia obciążenia i obsługuje wyłącznie API.

Nie musisz się przenosić. Adres główny nadal obsługuje /v1 dla istniejących integracji, bez daty zakończenia i bez przekierowania. Przenieś się, kiedy Ci to odpowiada, aby skorzystać z zalet adresu API, i używaj go we wszystkich nowych integracjach.

Co pozostaje bez zmian

Ścieżki, parametry, pola, kody błędów i zdarzenia: GET /v1/cards to to samo żądanie pod obydwoma adresami.
Klucze API. Te same klucze kb_ i kbsrc_ działają pod obydwoma adresami, z tą samą rolą, zakresami i profilem dostępu.
Klucze idempotencji, limity częstotliwości i przydziały. Żądania pod obydwoma adresami liczą się do tych samych przydziałów organizacji.
Webhooki. Dostarczenia, podpisy i sekrety nie zależą od adresu, który wywołujesz.
Linki w odpowiedziach. doc_url błędu prowadzi do tego portalu, a nagłówek Link strony listy prowadzi do adresu API, niezależnie od tego, który adres wywołujesz.

Czym różni się adres API

Pod adresem głównym	Pod adresem API
Każda operacja aplikacji webowej, w tym operacje wewnętrzne	Tylko operacje z publicznej dokumentacji API. Każda inna ścieżka odpowiada `404` z kodem `api.not_found`.
Klucz w `X-API-Key` lub `Authorization` albo plik cookie sesji przeglądarki	Klucz lub token dostępu OAuth, najlepiej w `Authorization: Bearer`. Pliki cookie są ignorowane.
`GET /auth/me`	`GET /v1/me`. Ścieżki pod `/auth/` nie są obsługiwane.
Tryb „View as” (podgląd jako wybrana rola i profil dostępu) przez plik cookie	Nagłówek `X-View-As` dla kluczy z rolą `admin`.
Jeden serwer lub stały zestaw serwerów	Kilka serwerów za modułem równoważenia obciążenia.

Ostatni wiersz ma znaczenie tylko w jednym przypadku: strumieniowanej odpowiedzi POST /v1/chat. Przerwany strumień jest kontynuowany od Last-Event-ID tylko na serwerze, który przygotowuje odpowiedź. Jeśli Twoja integracja wznawia strumienie, nadawaj każdemu pytaniu request_id, aby ponowienie na innym serwerze otrzymało zapisaną odpowiedź zamiast drugiej. Zob. Wznów przerwany strumień.

Zanim się przeniesiesz

Sprawdź, czy każde wywołanie jest publiczne. Wypisz ścieżki, które wywołuje Twoja integracja, i wyszukaj każdą z nich w dokumentacji API albo porównaj je ze specyfikacją nowego adresu:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

Ścieżka, której brakuje w publicznej dokumentacji, należy do aplikacji webowej. Nadal działa pod adresem głównym, ale nie jest obsługiwana pod adresem API, a jej struktura nie jest publicznym zobowiązaniem. Zastąp ją publiczną operacją albo pozostaw tę część integracji na adresie głównym i powiedz swojej osobie kontaktowej w Sursie, czego potrzebujesz.

Sprawdź sposób uwierzytelniania. Jeśli integracja loguje się hasłem użytkownika i plikiem cookie sesji, najpierw przenieś ją na klucz API. Jeśli wysyła X-API-Key, przejście na Authorization: Bearer jest zalecane, ale nie wymagane.

Sprawdź sieć. Zezwól w zaporze sieciowej i serwerach proxy na wychodzący ruch HTTPS do nowej nazwy hosta.

Przenieś się krok po kroku

Zrób z bazowego adresu URL ustawienie swojej integracji, jeśli jeszcze nim nie jest.

Wypróbuj nowy adres żądaniem odczytu:

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

Uruchom zestaw testów swojej integracji na nowym adresie, z kluczem testowym i kolekcją testową.
Przełącz część ruchu, np. jeden proces roboczy lub jedno środowisko, i obserwuj w dziennikach 404 api.not_found, 401 i 5xx. Każda odpowiedź zawiera X-Request-Id; zapisuj go w swoich dziennikach.
Przełącz resztę. Zachowaj przez jakiś czas stary bazowy adres URL w konfiguracji, aby móc wrócić w kilka sekund.

Co sprawdzić po przeniesieniu

GET /v1/health pod nowym adresem zwraca tę samą version co pod starym.
Odpowiedzi zawierają nagłówki RateLimit. Jeśli Twoja integracja sama zwalnia według X-RateLimit-*, może tak robić dalej: wysyłane są oba zestawy. Zob. Limity częstotliwości i przydziały.
Jeśli Twoja integracja działa w przeglądarce, nie potrzebuje już własnego serwera proxy dla CORS: adres API zezwala na żądania z dowolnego pochodzenia, bez plików cookie.