import Alert from '@/components/docs/Alert.astro';
import Cards from '@/components/docs/Cards.astro';
import Card from '@/components/docs/Card.astro';

U ovom odjeljku opisan je web-API (Web API) platforme, realiziran kao paket podataka REST API za razmjenu u formatu `json`.

## Opće napomene

- **Format prijenosa podataka**
  Web-API je realiziran kao paket podataka REST API za razmjenu u formatu json.
- **Postupak autentifikacije**
  Autentifikacija se temelji na dinamički ažuriranom tokenu, što jamči sigurnost primljenih podataka i sprječava curenje tokena.
- **Format varijabli s datumom i vremenom**
  Web-API vraća podatke tipa datum i vrijeme kodirane kao UNIX vrijeme ili POSIX vrijeme, u formatu `UTC: 1613376963`. Pri pretvorbi Unix vremena u čitljiv datum morate navesti vremensku zonu.
- **Straničenje**
  Web-API podržava straničenje radi preuzimanja podataka stranicu po stranicu. Broj stranice prosljeđuje se parametrom: `page="page number" (page=1)`. Broj zapisa koje upit vraća može se zadati parametrom per_page, ali ne više od 1.000 zapisa.

## Osnovni URL

Svi primjeri na ovim stranicama koriste sljedeći osnovni URL:

```bash
https://api.vadsro.eu/api/v1
```

<Alert type="info">
  Pri implementaciji na infrastrukturi korisnika (on-premise) zamijenite host adresom vlastite
  instalacije. Putanja `/api/v1` i sve krajnje točke (endpoints) unutar nje ostaju iste.
</Alert>

## Autentifikacija

Autentifikacija se temelji na dinamički ažuriranom tokenu. U praksi to izgleda ovako:

- Početna autentifikacija obavlja se pomoću adrese e-pošte i lozinke koje postoje u sustavu, a kao odgovor stižu dinamički token i povezani atributi.
- Oblikuje se ciljni zahtjev za preuzimanje podataka, a u zaglavlja HTTP zahtjeva dodaje se token dobiven u prethodnom koraku.
- Zahtjev se šalje poslužitelju. Ako je zahtjev ispravno oblikovan, poslužitelj vraća podatke u tijelu odgovora i novi token u zaglavljima odgovora, a stari token postaje nevažeći. S novim tokenom možete ponoviti prethodni korak i tako dalje.
- Po završetku rada posljednji token može se poništiti odjavom (SignOut) prije isteka roka valjanosti.

<Alert type="info">
  Ukratko, to znači da svaki sljedeći zahtjev prema web-API-ju mora sadržavati 4 zaglavlja iz
  prethodnog odgovora.
</Alert>

Za početnu autentifikaciju koriste se adresa e-pošte i lozinka postojećeg korisnika. U tu svrhu pošaljite POST zahtjev na adresu:

```bash
https://api.vadsro.eu/api/v1/auth/sign_in
```

Primjer zahtjeva u formatu Curl:

```bash
curl -i --header "Content-Type: application/json" \
     --request POST \
     --data '{"email":"api-user@example.com","password":"Str0ngPas$"}'\
     https://api.vadsro.eu/api/v1/auth/sign_in
```

Kao odgovor stiže sljedeća poruka:

```bash
HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: EXAMPLE-ACCESS-TOKEN-1
token-type: Bearer
client: EXAMPLE-CLIENT-ID
expiry: 1615227012
uid: api-user@example.com
ETag: W/"5b9bcc76f7223b72b79d9f2d31ff0fd5"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: c18e06b4-e5bd-40b5-875d-7ac958e2fbb5
X-Runtime: 0.391069
Transfer-Encoding: chunked
{"data":{"id":6,"email":"api-user@example.com","provider":"email","uid":"api-user@example.com","name":"API user"}}
```

U ovom odgovoru zanimaju nas sljedeća zaglavlja:

| Zaglavlje      | Opis                                                                                                                                                      |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token` | Vrijednost ovog zaglavlja koristi se kao lozinka za svaki zahtjev. Vrijednost se mijenja sa svakim zahtjevom.                                             |
| `client`       | Ovo je zaglavlje jedinstveno za trenutačnu vezu. Omogućuje više aktivnih sesija istodobno.                                                                |
| `expiry`       | Vrijeme kada ovaj token istječe. Zadana vrijednost je 2 tjedna od primitka tokena. Ili ranije, nakon odjave (SignOut). Nije potrebno za sljedeći zahtjev. |
| `uid`          | Jedinstvena vrijednost koja identificira korisnika. U našem slučaju to je adresa e-pošte.                                                                 |
| `token-type`   | Tip tokena koji se koristi.                                                                                                                               |

Primjer zahtjeva s tokenom iz prethodnog odgovora:

```bash
curl -i --header "access-token: EXAMPLE-ACCESS-TOKEN-1" \
 --header "token-type: Bearer" \
 --header "client: EXAMPLE-CLIENT-ID" \
 --header "uid: api-user@example.com" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"page":"2"}' \
 https://api.vadsro.eu/api/v1/stations
```

Kao odgovor stiže sljedeća poruka:

```bash
HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: EXAMPLE-ACCESS-TOKEN-2
token-type: Bearer
client: EXAMPLE-CLIENT-ID
expiry: 1615311367
uid: api-user@example.com
ETag: W/"ba0df406b647bd92f0bf3a18916714c1"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 35a26441-ae78-48fa-8b2e-e92d2605133b
X-Runtime: 0.167748
Transfer-Encoding: chunked
{"data": [
{"id":1,"name":"860000000000001","equipment_brand_name":"Corrector BK","phone":"","equipment_id":1},...
 ],
"total_pages":7,
"current_page":2
}
```

Da biste završili rad, možete se odjaviti (SignOut) ili spremiti potrebna zaglavlja iz posljednjeg zahtjeva i, ako rok valjanosti tokena nije istekao, upotrijebiti ih sljedeći put.

<Alert type="warning">
  Imajte na umu da će posljednji token, ako ne završite sesiju, vrijediti dva tjedna.
</Alert>

Završetak sesije:

```bash
curl -i --header "access-token: EXAMPLE-ACCESS-TOKEN-2" \
 --header "token-type: Bearer" \
 --header "client: EXAMPLE-CLIENT-ID" \
 --header "uid: api-user@example.com" \
 --request DELETE \
 https://api.vadsro.eu/api/v1/auth/sign_out
HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
ETag: W/"c955e57777ec0d73639dca6748560d00"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: b4b69ac3-5cba-4e6e-b6a0-f6577298c166
X-Runtime: 0.141467
Transfer-Encoding: chunked
{"success":true}
```

## Sljedeći koraci

Sada kada znate kako se obavlja autentifikacija, upoznajte se s osnovnim resursima API-ja:

<Cards cols={2}>
  <Card
    icon="network"
    title="Opskrbljivači i krajnji kupci"
    description="Preuzmite hijerarhiju opskrbljivača i popis krajnjih kupaca koje opslužuju."
    link="/hr/api/v1/resource-providers-and-consumers"
  />
  <Card
    icon="gauge"
    title="Mjerna mjesta"
    description="Preuzmite popis mjernih mjesta i njihove fizičke karakteristike."
    link="/hr/api/v1/metering-units"
  />
  <Card
    icon="archive"
    title="Arhive očitanja"
    description="Preuzmite očitanja kanala po tipu arhive i vremenskom intervalu."
    link="/hr/api/v1/readings-archives"
  />
  <Card
    icon="bell"
    title="Događaji i poruke"
    description="Pregledajte arhive događaja uređaja i šifrarnik kodova poruka."
    link="/hr/api/v1/events-and-messages"
  />
</Cards>