---
name: rest-client
description: REST API client with Swagger/OpenAPI support (like Insomnia/Postman in the terminal) — list endpoints from swagger, inspect request/response schemas, execute HTTP calls with configured auth. Use when the user wants to call, test, or explore a REST API, mentions an endpoint, swagger, or asks "strzel w API".
---

# REST API (Swagger/OpenAPI)

Wszystkie operacje przez `scripts/api.py`. API definiuje się w `.env` (patrz
`.env.example`, sekcja API) — **nigdy nie wypisuj wartości `API_*_AUTH`**.
Definicje Swagger tylko w formacie JSON (dla .NET/Swashbuckle to standardowo
`/swagger/v1/swagger.json`).

## Polecenia

```powershell
python .claude/skills/rest-client/scripts/api.py apis                 # co jest skonfigurowane

# eksploracja definicji (cache w .api-cache/, --refresh odswieza)
python .claude/skills/rest-client/scripts/api.py endpoints CRM
python .claude/skills/rest-client/scripts/api.py endpoints CRM --filter customer
python .claude/skills/rest-client/scripts/api.py describe CRM POST /api/customers

# requesty
python .claude/skills/rest-client/scripts/api.py call CRM GET /api/customers/123
python .claude/skills/rest-client/scripts/api.py call CRM GET /api/customers --query page=1 --query size=20
python .claude/skills/rest-client/scripts/api.py call CRM POST /api/customers --data '{"name": "Jan"}'
python .claude/skills/rest-client/scripts/api.py call CRM PUT /api/customers/123 --file body.json
python .claude/skills/rest-client/scripts/api.py call CRM GET /api/report --out raport.json   # duze odpowiedzi
```

## Zalecany tryb pracy

1. Nowe/nieznane API: `endpoints <API> --filter <temat>` zamiast zgadywania sciezek.
2. Przed POST/PUT: `describe` pokazuje pelny schemat body (pola wymagane,
   typy, enumy, zagniezdzenia — $ref-y sa rozwiazywane automatycznie).
3. W sciezce podstawiaj konkretne wartosci za `{parametry}` — skrypt odrzuci
   sciezke z niewypelnionym `{id}`.
4. Body JSON: krotkie inline przez `--data`; dluzsze zapisz do pliku w scratchpadzie
   i uzyj `--file` (unikniesz problemow z cudzyslowami w PowerShell).
5. Statusy 4xx/5xx NIE sa bledem skryptu — odpowiedz (tresc bledu z API) jest
   normalnie wypisywana; to cenna informacja diagnostyczna przy testowaniu.

## Budowanie requestow z danych uzytkownika

Uzytkownik zwykle podaje dane nieformalnie ("user to xx", "utworz klienta Jan
Kowalski z Warszawy") — nie gotowy JSON. Wtedy:

1. **Znajdz endpoint** (`endpoints --filter`), a potem `describe` — schemat body
   jest jedynym zrodlem prawdy o polach, typach i wymagalnosci.
2. **Zmapuj dane uzytkownika na schemat.** Brakuje pola wymaganego? Zapytaj
   uzytkownika — nie wymyslaj wartosci (szczegolnie identyfikatorow, kwot, dat).
   Pola opcjonalne, ktorych nie podal, pomijaj zamiast zgadywac.
3. **Pokaz zlozony request** (metoda, URL, body) przed wyslaniem — przy
   operacjach modyfikujacych poczekaj na potwierdzenie.
4. **Sprawdz wynik po wykonaniu:**
   - 2xx przy zapisie → potwierdz odczytem: `call GET` na utworzony/zmieniony
     zasob (id zwykle jest w odpowiedzi) i porownaj z danymi wejsciowymi;
     jesli zasob ma odbicie w bazie, mozna tez zweryfikowac skillem `mssql`;
   - 400 → przeczytaj bledy walidacji z odpowiedzi, popraw body, pokaz roznice
     i sprobuj ponownie (poprawki formatu/typow bez ponownego pytania; zmiany
     wartosci biznesowych — po potwierdzeniu);
   - 401/403 → token do odswiezenia w .env / brak uprawnien — zglos uzytkownikowi;
   - 5xx → pokaz tresc bledu; nie ponawiaj automatycznie requestow modyfikujacych.
5. Przy serii podobnych wywolan (np. "sprawdz jeszcze dla usera yy") uzywaj tego
   samego wzorca requestu, podmieniajac tylko dane.

## Zasady

- **Requesty modyfikujace (POST/PUT/PATCH/DELETE) wykonuj tylko na wyrazne
  polecenie uzytkownika** — pokaz wczesniej metode, URL i body. Wyjatek: gdy
  uzytkownik wprost testuje API i prosi o serie wywolan. `API_READONLY=true`
  (globalnie) lub `API_<NAZWA>_READONLY=true` blokuje wszystko poza GET/HEAD/OPTIONS.
- Odpowiedzi sa formatowane (JSON) i obcinane do `API_MAX_RESPONSE` znakow —
  duze odpowiedzi zapisuj przez `--out` i analizuj plik narzedziami (Grep/Read).
- Auth wstrzykiwany automatycznie z `.env`; dodatkowe naglowki przez
  `--header "Nazwa: wartosc"`.
- Wygasly token (401): poinformuj uzytkownika, ze trzeba odswiezyc `API_<NAZWA>_AUTH` w `.env`.

## Konfiguracja nowego API (w .env)

```
API_CRM_BASEURL=https://crm.twojbank.pl
API_CRM_SWAGGER=https://crm.twojbank.pl/swagger/v1/swagger.json
API_CRM_AUTH=bearer eyJhbGci...
# formaty auth: "bearer <token>" | "basic user:haslo" | "header X-Api-Key: sekret" | puste
```