API LinkHarbor w skrócie

REST API pozwala sterować LinkHarbor z własnych programów: tworzyć strony i linki, edytować i publikować wersje robocze, generować krótkie linki albo pobierać statystyki do własnych raportów. Ten artykuł jest dla programistów i wyjaśnia podstawowe zasady, które obowiązują dla każdego endpointu.

#Który sposób pasuje?

#Adres bazowy i wersjonowanie

Adres bazowy

https://dock.at-harbor.com – wszystkie endpointy produktu znajdują się pod /v1, na przykład https://dock.at-harbor.com/v1/pages.

Wersja

Obecnie istnieje tylko wersja v1. Numer wersji jest częścią ścieżki.

Protokół

Tylko HTTPS.

OpenAPI

Opis czytelny maszynowo (OpenAPI 3.1) znajdziesz pod adresem https://dock.at-harbor.com/openapi.yaml. Możesz go wczytać do Postmana, Insomnii lub generatora kodu.

#Testowanie w sandboxie

Do programowania i testów służy osobny sandbox. Zachowuje się jak prawdziwe API, ale jest od niego całkowicie oddzielony: ma własne konta i własne dane, a nic z tego nie trafia do Twojego prawdziwego workspace.

API

https://drydock.at-harbor.com, z tymi samymi ścieżkami co wyżej, na przykład https://drydock.at-harbor.com/v1/pages.

Panel

https://sandbox-deck.linkharbor.com, na przykład do tworzenia kluczy API.

Strony

Opublikowane strony pojawiają się pod adresem https://<handle>.sandbox.linkharbor.com.

Konto

Twoje prawdziwe konto LinkHarbor tam nie działa. Załóż osobne konto w sandboxie.

Sandbox nie wysyła e-maili. Jeśli rejestrujesz się przez API (POST /v1/auth/register), kod weryfikacyjny wraca bezpośrednio w odpowiedzi, w polu _dev_verification. To samo dotyczy resetowania hasła i zmiany adresu e-mail. To pole istnieje tylko w sandboxie, więc nie polegaj na nim w swoim kodzie.

• Powiadomienia push są wyłączone
• Płatności działają w trybie testowym Stripe, nie są przelewane żadne prawdziwe pieniądze
• Limity zapytań wynoszą około jednej trzeciej prawdziwych wartości, a nowe konta są ograniczone do 5 na godzinę i adres IP
• 1 dnia każdego miesiąca o 3:00 UTC sandbox jest całkowicie czyszczony, a wszystkie konta i dane znikają
• Każda odpowiedź zawiera nagłówek X-Environment: sandbox

#Uwierzytelnianie w skrócie

1. Jako właściciel lub admin utwórz w panelu w sekcji „Callback i API” klucz API z potrzebnymi zakresami (od planu Creator Pro)
2. Wymień ID klucza i sekret klucza na token dostępu przez POST /v1/token
3. Wysyłaj token z każdym żądaniem w nagłówku Authorization: Bearer …
4. Po 15 minutach pobierz nowy token

Wszystkie szczegóły znajdziesz w artykule Klucze API i tokeny dostępu, a uprawnienia w artykule Zakresy.

#Żądania i odpowiedzi

Format

Żądania i odpowiedzi to JSON w UTF-8. Przesyłanie plików korzysta też z multipart/form-data.

Content-Type

Przy każdym żądaniu z treścią wysyłaj nagłówek Content-Type: application/json. Każdy inny typ zostaje odrzucony z kodem 400 bad_request – także ten, który curl ustawia automatycznie dla -d, gdy brakuje tego nagłówka.

Nieznane pola

Pola, których endpoint nie zna, prowadzą do 422 validation_failed. Odpowiedź wymienia nieznane pola.

Uszkodzony JSON

Prowadzi do 400 invalid_json.

Rozmiar

W zależności od endpointu treść żądania może mieć najwyżej 64 KB, 1 MB lub 2 MB, a przesyłany plik 10 MB. Jeśli jest większa, API odpowiada kodem 413 request_too_large. Wszystkie limity znajdziesz w artykule Limity zapytań.

Listy

Przychodzą jako obiekt z polem items, na przykład {"items":[…]}.

Tworzenie

Odpowiada kodem HTTP 201 i nowym ID, na przykład {"id":123}.

Akcje bez wartości zwrotnej

Odpowiadają {"ok":true}.

Błędy

Zawsze mają stały format z kodem czytelnym maszynowo. Zobacz Format błędów API i kody błędów.

#Paginacja

Nie ma jednego schematu paginacji. Większość list jest mała i przychodzi w całości; tylko kilka endpointów ma parametry:

Dla sort przy krótkich linkach dostępne są created_desc, created_asc, redirects_desc i redirects_asc; q przeszukuje slug, tytuł i docelowy URL (do 100 znaków, bez rozróżniania wielkości liter). W statystykach period przyjmuje 24h, 7d, 30d, 90d, this_month, last_month, last_30d i custom; alternatywnie podajesz from i to. granularity to hour lub day.

#ID żądania i język

• Każda odpowiedź zawiera nagłówek X-Request-Id – podaj go, gdy kontaktujesz się z pomocą techniczną
• Jeśli wyślesz własny nagłówek X-Request-Id, API go użyje
• Tekst błędu w message jest w języku konta właściciela workspace, a w przeciwnym razie zależy od Accept-Language; kod w error zawsze pozostaje taki sam

#Wywołania z przeglądarki?

Technicznie API pozwala na wywołania z przeglądarki (CORS). Ale sekret klucza nigdy nie powinien trafić do kodu, który działa po stronie odwiedzającego – ani na stronie internetowej, ani w aplikacji. Zawsze wywołuj API z własnego serwera.

#Plany

Plany nie mają limitu liczby wywołań API. Obowiązują tylko minutowe limity zapytań. Limity treści Twojego planu – np. liczba stron, linków czy bloków na stronę – obowiązują w API tak samo jak w panelu. Zobacz Porównanie planów.

#Twoje pierwsze wywołanie

# Wymień klucz na token
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# Lista stron (zakres read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

Pełny przykład, który dodaje link, zmienia wygląd i publikuje stronę, znajdziesz w artykule Aktualizacja strony przez API.