Przejdź do głównej zawartości

Przegląd API

Notifer zapewnia prosty REST API do programowego dostępu do tematów, wiadomości i subskrypcji.

Bazowy URL​

https://app.notifer.io

Wszystkie punkty końcowe API są udostępniane z tej samej domeny co aplikacja webowa.

Struktura API​

Notifer API podąża za zasadami REST i używa:

  • Metody HTTP: GET, POST, PUT, PATCH, DELETE
  • JSON dla treści żądań/odpowiedzi (z wyjątkiem prostego publikowania)
  • Standardowe kody statusu HTTP
  • Tokeny JWT do uwierzytelniania

Przegląd punktów końcowych​

Publikowanie wiadomości​

MetodaPunkt końcowyOpis
POST/{topic}Publikowanie wiadomości do tematu
PUT/{topic}Publikowanie wiadomości do tematu (alias)

Zarządzanie tematami​

MetodaPunkt końcowyOpis
GET/api/topicsLista wszystkich tematów
GET/api/topics/myLista tematów użytkownika (wymaga uwierzytelnienia)
GET/api/topics/publicLista publicznych/odkrywalnych tematów
POST/api/topicsUtworzenie nowego tematu (wymaga uwierzytelnienia)
GET/api/topics/{name}Pobieranie szczegółów tematu po nazwie
GET/api/topics/{name}/statsPobieranie statystyk tematu
GET/api/topics/{name}/messagesWyszukiwanie wiadomości w temacie
PATCH/api/topics/{topic_id}Aktualizacja ustawień tematu (po UUID)
DELETE/api/topics/{topic_id}Usunięcie tematu (po UUID)

Wiadomości​

MetodaPunkt końcowyOpis
GET/{topic}/jsonPobieranie historii wiadomości (JSON)
GET/api/messages/searchWyszukiwanie wiadomości z filtrami
GET/api/messages/recentPobieranie ostatnich wiadomości z subskrybowanych tematów
GET/api/messages/activityPobieranie statystyk aktywności wiadomości dla wykresów
DELETE/api/{topic}/messages/{id}Miękkie usunięcie wiadomości (ESSENTIALS+)
PATCH/api/{topic}/messages/{id}Edycja wiadomości (ESSENTIALS+)

Subskrypcje w czasie rzeczywistym​

MetodaPunkt końcowyOpis
GET/sseSubskrypcja wielu tematów (multi-SSE)
POST/api/sse/sessionsUtworzenie sesji SSE dla krótkich URL
GET/{topic}/sseSubskrypcja pojedynczego tematu przez SSE
WS/{topic}/wsSubskrypcja przez WebSocket

Uwierzytelnianie​

MetodaPunkt końcowyOpis
POST/auth/registerRejestracja nowego użytkownika
POST/auth/loginLogowanie (email/hasło)
GET/auth/google/loginInicjowanie Google OAuth
POST/auth/apple/mobileApple Sign-In (iOS)
GET/auth/mePobieranie informacji o bieżącym użytkowniku
POST/auth/refreshOdświeżanie tokenu dostępu
GET/auth/verify-emailWeryfikacja adresu email
POST/auth/resend-verificationPonowne wysłanie emaila weryfikacyjnego
POST/auth/password-reset/requestŻądanie resetowania hasła
POST/auth/password-reset/confirmPotwierdzenie resetowania hasła
POST/auth/password-changeZmiana hasła
POST/auth/accept-termsAkceptacja Regulaminu
GET/auth/consent-historyPobieranie historii zgód (GDPR)

Zarządzanie użytkownikami​

MetodaPunkt końcowyOpis
GET/api/users/mePobieranie profilu bieżącego użytkownika
PATCH/api/users/meAktualizacja profilu użytkownika
GET/api/users/me/dataEksport danych użytkownika (GDPR)
DELETE/api/users/meUsunięcie konta (GDPR)

Urządzenia (Mobile)​

MetodaPunkt końcowyOpis
POST/api/devices/registerRejestracja urządzenia do push
GET/api/devices/myLista urządzeń użytkownika
GET/api/devices/{id}Pobieranie szczegółów urządzenia
PUT/api/devices/{id}Aktualizacja urządzenia
DELETE/api/devices/{id}Usunięcie urządzenia
POST/api/devices/{id}/testWysłanie testowego powiadomienia

Subskrypcje​

MetodaPunkt końcowyOpis
GET/api/subscriptionsLista subskrypcji użytkownika
POST/api/subscriptionsUtworzenie subskrypcji
PATCH/api/subscriptions/{id}Aktualizacja ustawień subskrypcji
DELETE/api/subscriptions/{id}Usunięcie subskrypcji
DELETE/api/subscriptions/by-topic/{name}Anulowanie subskrypcji po nazwie tematu
GET/api/subscriptions/check/{name}Sprawdzenie czy subskrybowany

Klucze API​

MetodaPunkt końcowyOpis
GET/api/keysLista kluczy API
POST/api/keysUtworzenie klucza API
DELETE/api/keys/{key_id}Odwołanie klucza API

Tokeny dostępu do tematów​

MetodaPunkt końcowyOpis
GET/api/topics/{topic}/access-tokensLista tokenów
POST/api/topics/{topic}/access-tokensUtworzenie tokenu
DELETE/api/topics/{topic}/access-tokens/{token_id}Odwołanie tokenu

Zespoły (Plan TEAM+)​

MetodaPunkt końcowyOpis
GET/api/teamsLista zespołów użytkownika
GET/api/teams/statsPobieranie statystyk zespołu
GET/api/teams/deactivatedLista dezaktywowanych zespołów
POST/api/teamsUtworzenie zespołu
GET/api/teams/{team_id}Pobieranie szczegółów zespołu
PATCH/api/teams/{team_id}Aktualizacja zespołu
DELETE/api/teams/{team_id}Usunięcie zespołu
POST/api/teams/{team_id}/reactivateReaktywacja zespołu
GET/api/teams/{team_id}/membersLista członków zespołu
PATCH/api/teams/{team_id}/members/{user_id}Aktualizacja roli członka
DELETE/api/teams/{team_id}/members/{user_id}Usunięcie członka
POST/api/teams/{team_id}/invitesZaproszenie członka
GET/api/teams/{team_id}/invitesLista oczekujących zaproszeń
POST/api/teams/invites/acceptAkceptacja zaproszenia
POST/api/teams/invites/{id}/resendPonowne wysłanie zaproszenia
DELETE/api/teams/invites/{id}Anulowanie zaproszenia

Format odpowiedzi​

Odpowiedź sukcesu​

{
  "id": "uuid",
  "name": "my-topic",
  "created_at": "2025-01-15T10:30:00Z",
  "message_count": 42
}

Odpowiedź błędu​

{
  "detail": "Topic not found"
}

Kody statusu HTTP​

KodZnaczenie
200Sukces
201Utworzono
204Brak treści (pomyślne usunięcie)
400Nieprawidłowe żądanie (nieprawidłowe dane wejściowe)
401Nieuwierzytelniony (wymagane uwierzytelnienie)
403Zabronione (niewystarczające uprawnienia)
404Nie znaleziono
409Konflikt (np. nazwa tematu już istnieje)
422Nie można przetworzyć jednostki (błąd walidacji)
429Przekroczono limit częstotliwości
500Wewnętrzny błąd serwera

Ograniczanie częstotliwości​

Limity częstotliwości różnią się w zależności od planu subskrypcji:

Limity planów:

Gdy zostanie osiągnięty limit częstotliwości, API zwraca HTTP 429 z nagłówkiem:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1641024000

Paginacja​

Punkty końcowe list wspierają paginację:

GET /api/topics?limit=50&offset=0

Parametry:

  • limit - Maksymalna liczba elementów do zwrócenia (domyślnie: 50, max: 100)
  • offset - Liczba elementów do pominięcia (domyślnie: 0)

SDK i biblioteki​

Oficjalne SDK​

Biblioteki społeczności​

Sprawdź GitHub dla bibliotek tworzonych przez społeczność.

Przykłady​

Publikowanie z uwierzytelnianiem​

# Najpierw pobierz token JWT
TOKEN=$(curl -X POST https://app.notifer.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}' \
  | jq -r '.access_token')

# Publikowanie do prywatnego tematu
curl -d "Authenticated message" \
  -H "Authorization: Bearer $TOKEN" \
  https://app.notifer.io/my-private-topic

Tworzenie tematu​

curl -X POST https://app.notifer.io/api/topics \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "server-alerts",
    "access_level": "private",
    "description": "Production server monitoring",
    "is_discoverable": false
  }'

Subskrybowanie przez SSE​

# Publiczny temat
curl -N https://app.notifer.io/server-alerts/sse

# Prywatny temat
curl -N "https://app.notifer.io/server-alerts/sse?token=$TOKEN"

Następne kroki​

Wsparcie​