Dokumentacja API¶

Kompletna dokumentacja wszystkich punktów końcowych Notifer API.

Interaktywna dokumentacja

Najbardziej aktualna i interaktywna dokumentacja API dostępna jest na:

Swagger UI: https://app.notifer.io/docs
ReDoc: https://app.notifer.io/redoc

Bazowy URL¶

https://app.notifer.io

Publikowanie wiadomości¶

Publikowanie wiadomości do tematu.

POST /{topic}
PUT /{topic}

Nagłówki:

Content-Type: text/plain
X-Title: Message title (optional)
X-Priority: 1-5 (optional, default: 3)
X-Tags: tag1,tag2,tag3 (optional)
X-Markdown: true|false (optional, default: false)
Authorization: Bearer <token> (optional, for private topics)
X-API-Key: <api_key> (optional, alternative auth)

Treść żądania:

Plain text message content

Przykład:

curl -X POST https://app.notifer.io/server-alerts \
  -H "X-Title: Server Down" \
  -H "X-Priority: 5" \
  -H "X-Tags: critical,server,production" \
  -d "Production server prod-web-01 is not responding"

Odpowiedź: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "topic": "server-alerts",
  "message": "Production server prod-web-01 is not responding",
  "title": "Server Down",
  "priority": 5,
  "tags": ["critical", "server", "production"],
  "timestamp": "2025-01-15T10:30:00Z"
}

Tematy¶

Lista tematów¶

Pobieranie wszystkich tematów dla uwierzytelnionego użytkownika.

GET /api/topics

Nagłówki:

Authorization: Bearer <token>

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

Odpowiedź: 200 OK

[
  {
    "id": "uuid",
    "name": "server-alerts",
    "owner_id": "uuid",
    "access_level": "private",
    "description": "Production server monitoring",
    "is_discoverable": false,
    "message_count": 42,
    "subscriber_count": 5,
    "created_at": "2025-01-01T00:00:00Z",
    "last_message_at": "2025-01-15T10:30:00Z"
  }
]

Tworzenie tematu¶

Utworzenie nowego tematu.

POST /api/topics

Nagłówki:

Authorization: Bearer <token>
Content-Type: application/json

Treść żądania:

{
  "name": "my-topic",
  "access_level": "public|private|protected",
  "description": "Topic description (optional)",
  "is_discoverable": true,
  "icon_name": "bell",
  "icon_color": "blue"
}

Odpowiedź: 201 Created

Pobieranie tematu¶

Pobieranie szczegółów tematu.

GET /api/topics/{topic}

Odpowiedź: 200 OK

Aktualizacja tematu¶

Aktualizacja ustawień tematu.

PATCH /api/topics/{topic}

Nagłówki:

Authorization: Bearer <token>
Content-Type: application/json

Treść żądania:

{
  "description": "Updated description",
  "is_discoverable": false,
  "icon_name": "server",
  "icon_color": "red"
}

Odpowiedź: 200 OK

Usunięcie tematu¶

Trwałe usunięcie tematu.

DELETE /api/topics/{topic}

Nagłówki:

Authorization: Bearer <token>

Odpowiedź: 204 No Content

Wiadomości¶

Pobieranie historii wiadomości¶

Pobieranie historii wiadomości dla tematu (format JSON).

GET /{topic}/json

Parametry zapytania: - limit (int, opcjonalne): Maksymalna liczba wiadomości do zwrócenia (domyślnie: 100, max: 500) - since (ISO datetime, opcjonalne): Pobierz wiadomości od tej daty

Przykład:

curl "https://app.notifer.io/server-alerts/json?limit=50"

Odpowiedź: 200 OK

[
  {
    "id": "uuid",
    "topic_id": "uuid",
    "topic_name": "server-alerts",
    "message": "Server is down",
    "title": "Alert",
    "priority": 5,
    "tags": ["critical"],
    "timestamp": "2025-01-15T10:30:00Z"
  }
]

Wyszukiwanie wiadomości¶

Wyszukiwanie we wszystkich tematach użytkownika.

GET /api/messages

Nagłówki:

Authorization: Bearer <token>

Parametry zapytania: - q (string): Zapytanie wyszukiwania - topic (string, opcjonalne): Filtrowanie według nazwy tematu - tags (string, opcjonalne): Filtrowanie według tagów (oddzielone przecinkami) - priority_min (int, opcjonalne): Minimalny priorytet (1-5) - priority_max (int, opcjonalne): Maksymalny priorytet (1-5) - page (int, opcjonalne): Numer strony - per_page (int, opcjonalne): Elementów na stronę

Przykład:

curl "https://app.notifer.io/api/messages?q=server&tags=critical&priority_min=4" \
  -H "Authorization: Bearer $TOKEN"

Odpowiedź: 200 OK

Subskrypcje¶

Subskrybowanie przez SSE¶

Subskrybowanie tematu przez Server-Sent Events (połączenie długo-trwałe).

GET /{topic}/sse

Parametry zapytania: - token (string, opcjonalne): Token JWT dla prywatnych tematów - since_id (uuid, opcjonalne): Pobierz wiadomości od tego ID wiadomości

Przykład:

# Publiczny temat
curl -N https://app.notifer.io/public-topic/sse

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

Odpowiedź: Strumień SSE

event: message
data: {"id":"uuid","topic":"server-alerts","message":"Hello",...}

event: message
data: {"id":"uuid","topic":"server-alerts","message":"World",...}

Subskrybowanie przez WebSocket¶

Subskrybowanie tematu przez WebSocket.

WS /{topic}/ws

Parametry zapytania: - token (string, opcjonalne): Token JWT dla prywatnych tematów

Przykład:

const ws = new WebSocket('wss://app.notifer.io/my-topic/ws?token=<TOKEN>');

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log(message);
};

Uwierzytelnianie¶

Rejestracja¶

Rejestracja nowego konta użytkownika.

POST /auth/register

Treść żądania:

{
  "email": "user@example.com",
  "username": "username",
  "password": "strong-password"
}

Odpowiedź: 201 Created

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 86400
}

Logowanie¶

Logowanie przez email i hasło.

POST /auth/login

Treść żądania:

{
  "email": "user@example.com",
  "password": "password"
}

Odpowiedź: 200 OK

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 86400
}

Google OAuth¶

Logowanie lub rejestracja przez Google.

GET /auth/google

Przekierowuje do przepływu Google OAuth.

Pobieranie bieżącego użytkownika¶

Pobieranie profilu uwierzytelnionego użytkownika.

GET /auth/me

Nagłówki:

Authorization: Bearer <token>

Odpowiedź: 200 OK

{
  "id": "uuid",
  "email": "user@example.com",
  "username": "username",
  "avatar_url": null,
  "subscription_tier": "free",
  "created_at": "2025-01-01T00:00:00Z"
}

Odświeżanie tokenu¶

Odświeżanie tokenu dostępu przy użyciu tokenu odświeżania.

POST /auth/refresh

Treść żądania:

{
  "refresh_token": "eyJ..."
}

Odpowiedź: 200 OK

Klucze API¶

Lista kluczy API¶

Pobieranie wszystkich kluczy API dla uwierzytelnionego użytkownika.

GET /api/keys

Nagłówki:

Authorization: Bearer <token>

Odpowiedź: 200 OK

[
  {
    "id": "uuid",
    "name": "Production Server",
    "key_prefix": "noti_abc",
    "created_at": "2025-01-01T00:00:00Z",
    "expires_at": null,
    "last_used_at": "2025-01-15T10:00:00Z"
  }
]

Tworzenie klucza API¶

Utworzenie nowego klucza API.

POST /api/keys

Nagłówki:

Authorization: Bearer <token>
Content-Type: application/json

Treść żądania:

{
  "name": "CI/CD Pipeline",
  "expires_at": "2026-01-01T00:00:00Z"
}

Odpowiedź: 201 Created

{
  "id": "uuid",
  "key": "noti_abc123...",
  "name": "CI/CD Pipeline",
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": "2026-01-01T00:00:00Z"
}

Zapisz klucz

Pełny key jest pokazany tylko raz. Zapisz go bezpiecznie!

Odwołanie klucza API¶

Odwołanie klucza API.

DELETE /api/keys/{key_id}

Nagłówki:

Authorization: Bearer <token>

Odpowiedź: 204 No Content

Tokeny dostępu do tematów¶

Lista tokenów tematu¶

Pobieranie wszystkich tokenów dostępu dla tematu.

GET /api/topics/{topic}/access-tokens

Nagłówki:

Authorization: Bearer <token>

Odpowiedź: 200 OK

Tworzenie tokenu tematu¶

Utworzenie nowego tokenu dostępu do tematu.

POST /api/topics/{topic}/access-tokens

Treść żądania:

{
  "name": "External Service",
  "permissions": ["read", "write"],
  "expires_at": "2026-01-01T00:00:00Z"
}

Odpowiedź: 201 Created

Odwołanie tokenu tematu¶

Odwołanie tokenu dostępu do tematu.

DELETE /api/topics/{topic}/access-tokens/{token_id}

Odpowiedź: 204 No Content

Zespoły¶

Lista zespołów¶

Pobieranie wszystkich zespołów dla uwierzytelnionego użytkownika.

GET /api/teams

Nagłówki:

Authorization: Bearer <token>

Odpowiedź: 200 OK

Tworzenie zespołu¶

Utworzenie nowego zespołu.

POST /api/teams

Treść żądania:

{
  "name": "Engineering Team",
  "description": "DevOps and Backend"
}

Odpowiedź: 201 Created

Zaproszenie członka zespołu¶

Zaproszenie użytkownika do zespołu.

POST /api/teams/{team_id}/members

Treść żądania:

{
  "email": "member@example.com",
  "role": "member|admin"
}

Odpowiedź: 201 Created

Subskrypcje (Mobile/Push)¶

Rejestracja urządzenia¶

Rejestracja urządzenia mobilnego do powiadomień push.

POST /api/devices

Treść żądania:

{
  "pushToken": "ExponentPushToken[xxx]",
  "platform": "ios|android",
  "deviceId": "unique-device-id",
  "deviceName": "iPhone 13 Pro"
}

Odpowiedź: 201 Created

Utworzenie subskrypcji¶

Subskrybowanie urządzenia do tematu.

POST /api/subscriptions

Treść żądania:

{
  "device_id": "uuid",
  "topic_name": "server-alerts",
  "notification_settings": {
    "sound_enabled": true,
    "vibrate_enabled": true,
    "priority_threshold": 3,
    "tags_filter": []
  }
}

Odpowiedź: 201 Created

Odpowiedzi błędów¶

Wszystkie odpowiedzi błędów mają następujący format:

{
  "detail": "Error message"
}

Powszechne kody statusu¶

Kod	Znaczenie
200	Sukces
201	Utworzono
204	Brak treści (pomyślne usunięcie)
400	Nieprawidłowe żądanie
401	Nieuwierzytelniony
403	Zabronione
404	Nie znaleziono
409	Konflikt
422	Błąd walidacji
429	Przekroczono limit częstotliwości
500	Wewnętrzny błąd serwera

Ograniczanie częstotliwości¶

Zobacz Przegląd API - Ograniczanie częstotliwości dla szczegółów.

Następne kroki¶

Przewodnik uwierzytelniania - Poznaj metody uwierzytelniania
Przegląd API - Zrozumienie struktury API
Przewodnik publikowania - Publikowanie wiadomości
Przewodnik SSE - Subskrypcje w czasie rzeczywistym

Interaktywna dokumentacja¶

Najbardziej kompleksowa i aktualna dokumentacja API dostępna jest w interaktywnym Swagger UI:

https://app.notifer.io/docs

Interaktywna dokumentacja pozwala na: - Wykonywanie wywołań API bezpośrednio z przeglądarki - Przeglądanie wszystkich schematów żądań/odpowiedzi - Wyświetlanie szczegółowych opisów parametrów - Testowanie przepływów uwierzytelniania