Dokumentacja integracji składa się z trzech uzupełniających się źródeł: instrukcji konfiguracji, specyfikacji protokołu i informacji właściwych dla konkretnego konektora. Każde odpowiada na inne pytania.
| Źródło | Co z niego pobrać |
|---|---|
| Instrukcje bs4core.com | Jak włączyć usługę, ustawić dostęp, wywołać operacje i diagnozować błędy. |
| OpenAPI JSON / Swagger UI | Metody HTTP, ścieżki, parametry, schematy i przykłady odpowiedzi. |
| Pomoc dla developera w konektorze | Adres instalacji oraz rzeczywiste aliasy i listy klas/pól dostępnych dla tej integracji. |
Swagger i plik dla AI #
Dotychczasowa publiczna specyfikacja znajduje się pod adresami Swagger UI na bs4.io i OpenAPI JSON na bs4.io. Przygotowywana aktualizacja 1.02 uwzględnia poprawiony healthcheck oraz kontrakt triggerów. Do czasu opublikowania nowej paczki stare adresy pozostają punktem dostępu do wcześniejszej specyfikacji 1.01; różnice opisuje changelog.
Docelowo specyfikacja powinna być utrzymywana razem z instrukcją na bs4core.com, pod jednym adresem kanonicznym /apidocs/openapi.json, z interfejsem /apidocs/. Zmiana adresów wymaga publikacji plików i sprawdzenia ich dostępności; sam artykuł nie uruchamia hostingu Swaggera.
Aktualna paczka API 1.02 #
Pobierz Swagger UI i OpenAPI 1.02 (ZIP). Archiwum zawiera katalog apidocs z plikiem openapi.json oraz gotowym interfejsem Swagger UI. Po rozpakowaniu programista lub agent AI może korzystać z JSON jako kontraktu API. Specyfikację dopasuj do wersji swojej instalacji; wersja 1.02 wymaga aktualizacji BS4.
Do stałego hostingu należy umieścić katalog apidocs w głównym katalogu bs4core.com i sprawdzić oba docelowe adresy. Dopiero wtedy należy przekierować stare adresy bs4.io/apidocs/ i bs4.io/apidocs/openapi.json. Do tego czasu aktualna specyfikacja jest dostępna w powyższej paczce do pobrania.
Jak używać specyfikacji #
- Sprawdź wersję API instalacji, dla której piszesz integrację.
- Odczytaj kontrakt odpowiedniej operacji z OpenAPI. Pobierz plik do narzędzia programistycznego lub przekaż jego adres agentowi AI.
- Z pomocy dla developera pobierz rzeczywisty adres, aliasy klas/pól i dopuszczone operacje.
- Ustaw adres instalacji jako adres serwera API; nie wysyłaj żądań biznesowych do domeny dokumentacji.
- Przetestuj najpierw mały odczyt, a potem zapis na danych testowych i sprawdź stan w BS4.
Instrukcja dla AI #
Napisz integrację z bs4 API dla wskazanej wersji.
Użyj specyfikacji OpenAPI oraz przekazanej pomocy developera.
Nie wymyślaj aliasów klas, pól ani filtrów.
Token pobieraj z chronionej konfiguracji, nie wpisuj go do kodu.
Sprawdzaj status HTTP oraz success/errors.
Dla GET odczytuj obiekty z tablicy results.
Dla triggera odróżniaj wykonanie natychmiastowe od kolejki.
Po timeoutcie operacji zapisu nie ponawiaj jej automatycznie.
Wskaż informacje, których brakuje do poprawnej integracji.Do promptu nie wklejaj swojego tokena ani danych poufnych. Przekaż opis celu, schemat i zanonimizowane przykłady. Kod wygenerowany przez AI wymaga przeglądu i sprawdzenia; nie zastępuje konfiguracji konektora.
MCP ma własny katalog #
Plik OpenAPI opisuje REST API. Agent pracujący przez MCP powinien odkrywać schematy komend w połączonej instalacji, zgodnie z instrukcją Praca z bs4 core przez MCP.
