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

Această secțiune descrie interfața Web API a platformei, implementată ca pachet de date REST API pentru schimbul de date în format `json`.

## Precizări generale

- **Formatul de transfer al datelor**
  Interfața Web API este implementată ca pachet de date REST API pentru schimbul de date în format json.
- **Procedura de autentificare**
  Autentificarea se bazează pe un token actualizat dinamic, care garantează securitatea datelor primite și previne scurgerea tokenului.
- **Formatul variabilelor care conțin data și ora**
  Interfața Web API returnează valorile de tip dată și oră codificate în timp UNIX sau timp POSIX, în formatul `UTC: 1613376963`. La conversia timpului Unix într-o dată ușor de citit, trebuie indicat fusul orar.
- **Paginare**
  Interfața Web API implementează paginarea pentru descărcarea datelor pagină cu pagină. Numărul paginii se transmite în parametrul `page="page number" (page=1)`. Numărul de înregistrări returnate de o interogare se poate stabili prin parametrul per_page, dar cel mult 1.000 de înregistrări.

## Adresa URL de bază

Toate exemplele de pe aceste pagini folosesc următoarea adresă URL de bază:

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

<Alert type="info">
  La o instalare pe infrastructura clientului (on-premise), înlocuiți gazda cu adresa propriei
  instalări. Calea `/api/v1` și toate endpointurile de sub ea rămân aceleași.
</Alert>

## Autentificare

Autentificarea se bazează pe un token actualizat dinamic. În practică, procedura arată astfel:

- Autentificarea inițială se face cu o adresă de e-mail și o parolă existente în sistem, iar ca răspuns se primesc un token dinamic și atributele asociate.
- Se formează cererea propriu-zisă pentru obținerea datelor: în anteturile cererii HTTP se adaugă tokenul primit la pasul anterior.
- Cererea se trimite la server. Dacă cererea este formată corect, serverul returnează datele în corpul răspunsului și un token nou în anteturile răspunsului, iar tokenul vechi devine nevalid. Cu tokenul nou se poate repeta pasul anterior și așa mai departe.
- La încheierea lucrului, ultimul token poate fi invalidat înainte de data expirării (SignOut).

<Alert type="info">
  Pe scurt, fiecare cerere ulterioară către interfața Web API trebuie să conțină 4 anteturi din
  răspunsul anterior.
</Alert>

Autentificarea inițială folosește adresa de e-mail și parola unui utilizator existent. Pentru aceasta, trimiteți o cerere POST la adresa:

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

Exemplu de cerere în format 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
```

Ca răspuns se primește următorul mesaj:

```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"}}
```

Din acest răspuns ne interesează următoarele anteturi:

| Antet          | Descriere                                                                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token` | Valoarea acestui antet se folosește ca parolă la fiecare cerere. Valoarea se schimbă la fiecare cerere.                                                       |
| `client`       | Acest antet este unic pentru conexiunea curentă. Permite mai multe sesiuni active în același timp.                                                            |
| `expiry`       | Momentul în care expiră tokenul. Implicit, la 2 săptămâni de la primire sau, anticipat, prin SignOut. Acest antet nu este necesar pentru cererea următoare. |
| `uid`          | O valoare unică ce identifică utilizatorul. În cazul nostru, adresa de e-mail.                                                                                |
| `token-type`   | Tipul tokenului folosit.                                                                                                                                      |

Exemplu de cerere cu tokenul din răspunsul anterior:

```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
```

Ca răspuns se primește următorul mesaj:

```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
}
```

Pentru a încheia lucrul, puteți fie să folosiți procedura de deconectare (SignOut), fie să salvați anteturile necesare din ultima cerere și să le folosiți data viitoare, dacă durata de valabilitate a tokenului nu a expirat.

<Alert type="warning">
  Rețineți că, dacă sesiunea nu este încheiată, ultimul token rămâne valabil două săptămâni.
</Alert>

Încheierea sesiunii:

```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}
```

## Pașii următori

Acum că vă puteți autentifica, explorați resursele principale ale interfeței API:

<Cards cols={2}>
  <Card
    icon="network"
    title="Furnizori și consumatori"
    description="Obțineți ierarhia furnizorilor și consumatorii pe care îi deservesc."
    link="/ro/api/v1/resource-providers-and-consumers"
  />
  <Card
    icon="gauge"
    title="Puncte de măsurare"
    description="Obțineți lista punctelor de măsurare și citiți caracteristicile lor fizice."
    link="/ro/api/v1/metering-units"
  />
  <Card
    icon="archive"
    title="Arhivele citirilor"
    description="Obțineți citirile canalelor după tipul de arhivă și intervalul de timp."
    link="/ro/api/v1/readings-archives"
  />
  <Card
    icon="bell"
    title="Evenimente și mesaje"
    description="Citiți arhivele de evenimente ale dispozitivelor și nomenclatorul codurilor de mesaje."
    link="/ro/api/v1/events-and-messages"
  />
</Cards>