# Dokumentacja REST API v2: `/transports`

## Opis

Węzeł `/transports` służy do przeszukiwania transportów na podstawie różnych parametrów. Poniżej znajduje się szczegółowy opis dostępnych parametrów oraz sposobu ich użycia.

## Endpoint

`GET /transports -H APIVersion: v2`

## Parametry zapytania

Endpoint obsługuje różne parametry zapytania, które pozwalają na filtrowanie, sortowanie i ograniczanie wyników. Poniżej przedstawiono dostępne parametry oraz operatory:

### Filtrowanie

Możesz filtrować wyniki za pomocą parametrów określających różne właściwości transportów. Obsługiwane są następujące operatory:

| Operator | Opis | Przykład |
| --- | --- | --- |
| `eq` | Równe wartości | `/transports?erpIdentifier=123123`<br>`/transports?eq:erpIdentifier=123123` |
| `ne` | Różne wartości | `/transports?ne:erpIdentifier=123123` |
| `inn` | Wartość nie jest null | `/transports?inn:erpIdentifier` |
| `in` | Wartości w liście | `/transports?in:erpIdentifier=123456,929213` |
| `il` | Dopasowanie wzorca (ILIKE) | `/transports?il:erpIdentifier=%123` |
| `gt` | Wartości większe niż | `/transports?gt:dateCreated=2024-09-01` |
| `lt` | Wartości mniejsze niż | `/transports?lt:dateCreated=2024-09-01` |

#### Przykłady użycia:

- `/transports?erpIdentifier=123123` - Zwraca transporty, których `erpIdentifier` jest równy `123123`.
- `/transports?ne:erpIdentifier=123123` - Zwraca transporty, których `erpIdentifier` nie jest równy `123123`.
- `/transports?inn:erpIdentifier` - Zwraca transporty, których `erpIdentifier` nie jest null.
- `/transports?in:erpIdentifier=12345,67890` - Zwraca transporty, których `erpIdentifier` znajduje się na liście \['12345', '67890'\]
- `/transports?il:erpIdentifier=%123` - Zwraca transporty, na podstawie wzorca ILIKE `%123` dla pola `erpIdentifier`.
- `/transports?gt:dateCreated=2024-09-01` - Zwraca transporty utworzone po 2024-09-01.
- `/transports?gt:dateCreated=2024-09-01` - Zwraca transporty utworzone przed 2024-09-01.

#### Stosowanie daty:

W przypadku operatorów `gt` oraz `lt` możemy użyć danych typu data w formacie reprezentowanym przez ISO 8601. W aktualnejw wersji API v2 obsługujemy datę bez godziny, tzn. przyjmujemy format `yyyy-MM-dd`.

### Sortowanie

Wyniki można sortować za pomocą parametrów `sort` i `order`. - `sort`: Pole, po którym ma być sortowanie. - `order`: Kierunek sortowania (`asc` dla rosnącego, `desc` dla malejącego).

#### Przykład użycia:

- `/transports?sort=id&order=asc` - Sortuje wyniki rosnąco po polu `id`.

### Stronicowanie

Można określić, którą stronę wyników chcesz pobrać, za pomocą parametru page. Stronicowanie rozpoczyna się od 0.

- `page`: Numer strony do pobrania (indeksowany od 0). Domyślna wartość to 0.

#### Przykład użycia:

- `/transports?page=0&limit=10` - Zwraca pierwszą stronę wyników, maksymalnie 10 elementów.

### Ograniczanie wyników

Można ograniczyć liczbę zwracanych wyników za pomocą parametru `limit`. - `limit`: Liczba wyników do zwrócenia. Domyślną wartością jest 10, a maksymalna wartość to 100.

#### Przykład użycia:

- `/transports?limit=10` - Zwraca maksymalnie 10 wyników.

## Przykładowe zapytania

1. **Pobranie 10 transportów o `erpIdentifier` równym `123123`, posortowanych rosnąco po `id`:**

   ```
   GET /transports?erpIdentifier=123123&sort=id&order=asc&limit=10
   ```
2. **Pobranie wszystkich transportów, gdzie `erpIdentifier` nie jest równy `123123`:**

   ```
   GET /transports?ne:erpIdentifier=123123
   ```
3. **Pobranie wszystkich transportów, gdzie `erpIdentifier` nie jest null:**

   ```
   GET /transports?inn:erpIdentifier
   ```
4. **Pobranie drugiej strony wyników, po 10 elementów na stronę:**

   ```
   GET /transports?page=1&limit=10
   ```

## Przykładowa odpowiedź

Poniżej znajduje się przykładowa odpowiedź na zapytanie:

```
{
    "data": [
      "(...)"
    ],
    "metaData": {
        "currentPage": 0,
        "pageSize": 10,
        "totalItems": 2,
        "totalPages": 1
    },
   "status": 200
}
```

## Podsumowanie

Węzeł `/transports` API umożliwia zaawansowane przeszukiwanie transportów za pomocą różnych parametrów i operatorów. Pozwala na filtrowanie, sortowanie i ograniczanie wyników, co daje dużą elastyczność w pozyskiwaniu danych. W każdej odpowiedzi znajduje się także węzeł `metaData`, który zawiera informacje o aktualnej stronie, rozmiarze strony, łącznej liczbie elementów oraz liczbie stron. Stronicowanie rozpoczyna się od 0, a użytkownik może wybrać stronę wyników za pomocą parametru page. Domyślną wartością dla limit jest 10, a maksymalna wartość to 100. Domyślną wartością dla page jest 0.
