Dokumentacja API

Dokumentacja REST API

Interaktywna dokumentacja REST API aplikacji obejmująca moduł uwierzytelniania, zarządzanie działami organizacyjnymi, stanowiskami oraz profile użytkowników.

Informacje podstawowe

Base URL https://api.matmartech.com
Wersja API v1
Format danych application/json
Autoryzacja Bearer Token w nagłówku Authorization

Zakres dokumentacji

Moduł Opis
Auth API Obsługa rejestracji, logowania, pobrania danych aktualnie zalogowanego użytkownika oraz wylogowania.
Departments API Zarządzanie działami organizacyjnymi, w tym strukturą hierarchiczną opartą o relację dział nadrzędny – dział podrzędny.
User Profiles API Zarządzanie profilami użytkowników oraz przypisywaniem użytkowników do wybranych działów i stanowisk.
Positions API Zarządzanie słownikiem stanowisk oraz przypisywanie pojedynczego stanowiska do konkretnego użytkownika.

Domyślne nagłówki

Accept: application/json
Content-Type: application/json
Authorization: Bearer {token}

Nagłówek Authorization jest wymagany dla wszystkich endpointów chronionych, czyli modułów działów, profili oraz części endpointów uwierzytelniania, takich jak pobranie danych użytkownika i wylogowanie.

Dostępne grupy endpointów

Grupa Przykładowe endpointy Opis
Auth /api/v1/auth/register
/api/v1/auth/login
/api/v1/auth/me 		Rejestracja, logowanie, pobieranie danych zalogowanego użytkownika oraz zarządzanie tokenami dostępu.
Departments /api/v1/departments
/api/v1/departments/tree 		Tworzenie, odczyt, aktualizacja i soft delete działów oraz pobieranie ich struktury w formie drzewa.
User Profiles /api/v1/user-profiles
/api/v1/users/{user}/profile
/api/v1/users/{user}/department 		Tworzenie i aktualizacja profili użytkowników oraz zmiana działu użytkownika.
Positions /api/v1/positions
/api/v1/users/{user}/position 		CRUD stanowisk i zmiana przypisania użytkownika do stanowiska.

Standard odpowiedzi

Przykład odpowiedzi sukcesu

{
  "success": true,
  "message": "Operacja zakończona sukcesem.",
  "data": {}
}

Przykład błędu walidacji

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}

Kody statusów HTTP

Kod Nazwa Znaczenie
200 OK Operacja zakończona poprawnie.
201 Created Zasób został utworzony, np. użytkownik, dział lub profil.
401 Unauthorized Brak autoryzacji lub nieprawidłowy token dostępu.
422 Unprocessable Entity Błąd walidacji danych wejściowych.
500 Internal Server Error Nieobsłużony błąd po stronie serwera.

Przepływ autoryzacji

  1. Użytkownik wykonuje rejestrację albo logowanie.
  2. API zwraca token dostępu.
  3. Klient zapisuje token po stronie aplikacji.
  4. Każdy kolejny request do chronionego endpointu wysyła nagłówek Authorization: Bearer {token}.
  5. Przy wylogowaniu bieżący token albo wszystkie tokeny są usuwane.

Założenia modułów biznesowych

  • Działy mogą być organizowane hierarchicznie poprzez pole parent_id.
  • Usuwanie działów realizowane jest jako soft delete.
  • Stanowiska przechowywane są jako osobny słownik i również obsługują soft delete.
  • Profil użytkownika przechowuje rozszerzone dane użytkownika niezależnie od tabeli users.
  • Przypisanie użytkownika do działu odbywa się przez pole department_id w profilu użytkownika.
  • Użytkownik może mieć przypisane maksymalnie jedno stanowisko przez pole position_id.