Adres API i środowiska

Sursa API ma własny adres, oddzielny od adresu, pod którym ludzie otwierają Sursę w przeglądarce. Wszystkie ścieżki zaczynają się od /v1.

Gdzie działa Sursa	Adres API	Ten portal
Chmura Sursa	`https://api.sursa.com`	`https://developers.sursa.com`
Własna instalacja	`https://api.<your domain>`, zgodnie z konfiguracją administratora	`/developers/` pod adresem API
Twoja instalacja bez osobnego adresu API	adres główny instalacji	`/developers/` pod adresem głównym

Adres API obsługuje tylko API: nie ma pod nim strony logowania, plików cookie ani interfejsu webowego. Każde żądanie jest uwierzytelniane kluczem API lub tokenem dostępu OAuth. Adres może być obsługiwany przez kilka serwerów za modułem równoważenia obciążenia; Twoja integracja nie musi wiedzieć, ile ich jest.

Integracje, które wywołują API pod adresem głównym (np. https://app.sursa.com/v1), działają dalej. Kilka różnic i przejście krok po kroku opisuje przewodnik Przejdź na adres API.

Bazowy adres URL

Twórz każde żądanie na podstawie jednego bazowego adresu URL z konfiguracji, aby ten sam kod działał w dowolnym środowisku:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Używaj wyłącznie HTTPS i nie zapisuj klucza w dziennikach wysyłanych żądań.

Wersja i specyfikacja

GET /v1/health informuje, czy adres działa, i zwraca wersję Sursy, która go obsługuje. Odpowiada bez klucza, więc możesz używać tej operacji w monitoringu:

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

To wersja wydania Sursy, a nie API. Wersją API jest info.version jego specyfikacji. Specyfikacja OpenAPI 3.1 tego API jest publikowana pod tym samym adresem, bez uwierzytelniania:

Ścieżka	Zawartość
`GET /openapi.json`	Publiczna specyfikacja z tym adresem w `servers`.
`GET /v1/openapi-public.json`	Ta sama specyfikacja. Obsługuje `ETag` i `If-None-Match`.

Używaj jej do generowania klienta, do importu API do narzędzia takiego jak Postman lub do sprawdzania w CI, czy Twoja integracja używa tylko operacji oczekiwanej wersji. Dokumentacja API tego portalu jest budowana z tego samego pliku.

Testowanie

Sursa nie ma osobnego trybu testowego: każde żądanie z kluczem działa na prawdziwych danych jego organizacji. Aby bezpiecznie programować i testować:

Utwórz osobny klucz do programowania z najwęższą rolą i zakresami, jakich wymaga praca.
Zapisuj dane w osobnej kolekcji, np. sandbox, którą widzi tylko Twój zespół, i usuń ją po zakończeniu pracy.
Jeśli Twoja firma ma osobną organizację lub instalację Sursy do testów, skieruj na nią bazowy adres URL i klucz. Nic innego w Twoim kodzie się nie zmienia.
Od początku zadbaj o bezpieczne ponawianie: wysyłaj Idempotency-Key z każdym żądaniem POST i PATCH.

Konsola Wypróbuj na stronie każdej operacji w dokumentacji API wysyła prawdziwe żądania z kluczem, który do niej wkleisz. Klucz zostaje w pamięci karty przeglądarki i jest wysyłany tylko na adres API.

Wymagania sieciowe

Wychodzący ruch HTTPS (port 443) z Twoich serwerów na adres API.
W regułach zapory sieciowej, jeśli Twoja sieć na to pozwala, zezwalaj na nazwę hosta, a nie na stałe adresy IP: serwery za adresem mogą się zmieniać w miarę zwiększania przepustowości.
Aplikacje przeglądarkowe mogą wywoływać API bezpośrednio: odpowiedzi zezwalają na dowolne pochodzenie (Access-Control-Allow-Origin: *) bez plików cookie. Pamiętaj, że klucz używany w przeglądarce jest widoczny dla użytkownika tej przeglądarki.