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, 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¶

Metoda	Punkt końcowy	Opis
`POST`	`/{topic}`	Publikowanie wiadomości do tematu
`PUT`	`/{topic}`	Publikowanie wiadomości do tematu (alias)

Zarządzanie tematami¶

Metoda	Punkt końcowy	Opis
`GET`	`/api/topics`	Lista wszystkich tematów (wymaga uwierzytelnienia)
`POST`	`/api/topics`	Utworzenie nowego tematu (wymaga uwierzytelnienia)
`GET`	`/api/topics/{topic}`	Pobieranie szczegółów tematu
`PATCH`	`/api/topics/{topic}`	Aktualizacja ustawień tematu
`DELETE`	`/api/topics/{topic}`	Usunięcie tematu

Wiadomości¶

Metoda	Punkt końcowy	Opis
`GET`	`/{topic}/json`	Pobieranie historii wiadomości (JSON)
`GET`	`/api/messages`	Wyszukiwanie wiadomości (wymaga uwierzytelnienia)

Subskrypcje (Real-time)¶

Metoda	Punkt końcowy	Opis
`GET`	`/{topic}/sse`	Subskrybowanie przez Server-Sent Events
`WS`	`/{topic}/ws`	Subskrybowanie przez WebSocket

Uwierzytelnianie¶

Metoda	Punkt końcowy	Opis
`POST`	`/auth/register`	Rejestracja nowego użytkownika
`POST`	`/auth/login`	Logowanie (email/hasło)
`POST`	`/auth/google`	Logowanie przez Google OAuth
`GET`	`/auth/me`	Pobieranie informacji o bieżącym użytkowniku
`POST`	`/auth/refresh`	Odświeżanie tokenu dostępu

Zarządzanie użytkownikami¶

Metoda	Punkt końcowy	Opis
`GET`	`/api/users/me`	Pobieranie profilu bieżącego użytkownika
`PATCH`	`/api/users/me`	Aktualizacja profilu użytkownika
`DELETE`	`/api/users/me`	Usunięcie konta

Klucze API¶

Metoda	Punkt końcowy	Opis
`GET`	`/api/keys`	Lista kluczy API
`POST`	`/api/keys`	Utworzenie klucza API
`DELETE`	`/api/keys/{key_id}`	Odwołanie klucza API

Tokeny dostępu do tematów¶

Metoda	Punkt końcowy	Opis
`GET`	`/api/topics/{topic}/access-tokens`	Lista tokenów
`POST`	`/api/topics/{topic}/access-tokens`	Utworzenie tokenu
`DELETE`	`/api/topics/{topic}/access-tokens/{token_id}`	Odwołanie tokenu

Zespoły (Plan Pro/Team)¶

Metoda	Punkt końcowy	Opis
`GET`	`/api/teams`	Lista zespołów użytkownika
`POST`	`/api/teams`	Utworzenie 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}/members`	Zaproszenie członka

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¶

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

Ograniczanie częstotliwości¶

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

Plan Free¶

Publikowanie: 100 wiadomości/miesiąc łącznie
Tematy: Maksymalnie 3 tematy
Żądania API: 60 żądań/minutę na IP

Plan Pro¶

Publikowanie: 1,000 wiadomości/miesiąc
Tematy: Maksymalnie 50 tematów
Żądania API: 300 żądań/minutę na IP

Plan Team¶

Publikowanie: Bez ograniczeń
Tematy: Bez ograniczeń
Żądania API: 600 żądań/minutę na IP

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?page=1&per_page=20

Parametry: - page - Numer strony (domyślnie: 1) - per_page - Elementów na stronę (domyślnie: 20, max: 100)

Nagłówki odpowiedzi:

X-Total-Count: 150
X-Page: 1
X-Per-Page: 20

Interaktywna dokumentacja¶

Eksploruj pełne API interaktywnie używając Swagger UI:

https://app.notifer.io/docs

Lub w formacie ReDoc:

https://app.notifer.io/redoc

SDK i biblioteki¶

Oficjalne SDK¶

Python: notifer-python (Wkrótce)
JavaScript/Node.js: notifer-js (Wkrótce)
Go: notifer-go (Wkrótce)

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¶

Przewodnik uwierzytelniania - Poznaj metody uwierzytelniania
Dokumentacja API - Kompletna dokumentacja punktów końcowych
Przewodnik publikowania - Wysyłanie wiadomości przez HTTP
Przewodnik SSE - Subskrypcje w czasie rzeczywistym

Wsparcie¶

Interaktywna dokumentacja: https://app.notifer.io/docs
Email: support@notifer.io
GitHub Issues: https://github.com/notifer/notifer/issues