import Alert from '@/components/docs/Alert.astro';
import Cards from '@/components/docs/Cards.astro';
import Card from '@/components/docs/Card.astro';

Бұл бөлімде платформаның Web API интерфейсі сипатталған; ол `json` пішімінде деректер алмасуға арналған REST-API деректер пакеті түрінде іске асырылған.

## Жалпы ережелер

- **Деректерді беру пішімі**
  Web API json пішімінде деректер алмасуға арналған REST-API деректер пакеті түрінде іске асырылған.
- **Аутентификация тәртібі**
  Аутентификация динамикалық түрде жаңарып отыратын токенге негізделген; ол алынатын деректердің қауіпсіздігіне кепілдік беріп, токеннің таралып кетуін болдырмайды.
- **Күн мен уақытты қамтитын айнымалылардың пішімі**
  Web API «күн мен уақыт» типіндегі деректерді UNIX time немесе POSIX time кодтауында `UTC: 1613376963` пішімінде қайтарады. Unix time мәнін оқуға ыңғайлы күнге түрлендіргенде уақыт белдеуін көрсету қажет.
- **Беттеп шығару (pagination)**
  Web API интерфейсінде деректерді бетке бөліп жүктеуге арналған беттеп шығару мүмкіндігі іске асырылған. Ол параметрмен беріледі: `page="page number" (page=1)`. Сұрауда қайтарылатын жазбалар санын per_page параметрі арқылы көрсетуге болады, бірақ ол 1000 жазбадан аспауы тиіс.

## Базалық URL

Осы беттердегі барлық мысалдарда мынадай базалық URL пайдаланылады:

```bash
https://api.vadsro.eu/api/v1
```

<Alert type="info">
  Жеке серверде (on-premise) орналастырғанда хостты өз орнатылымыңыздың мекенжайымен ауыстырыңыз.
  `/api/v1` жолы және оның астындағы барлық соңғы нүктелер (endpoint) өзгеріссіз қалады.
</Alert>

## Аутентификация

Аутентификация динамикалық түрде жаңарып отыратын токенге негізделген. Іс жүзінде бұл былай жүзеге асады:

- Бастапқы аутентификация жүйеде бар электрондық пошта мекенжайы мен құпиясөз арқылы орындалады; жауап ретінде динамикалық токен және онымен байланысты атрибуттар алынады.
- Деректерді алуға арналған мақсатты сұрауды қалыптастыру: алдыңғы қадамда алынған токен HTTP сұрауының тақырыптамаларына қосылады.
- Сұрауды серверге жіберу. Сұрау дұрыс қалыптастырылған болса, сервер жауап денесінде деректерді, ал жауап тақырыптамаларында жаңа токенді қайтарады, ескі токен болса жарамсыз болып қалады. Жаңа токенмен алдыңғы қадамды қайталауға болады — және осылай жалғаса береді.
- Жұмыс аяқталған соң, соңғы токенді жарамдылық мерзімі өтпей тұрып жарамсыз етуге болады (SignOut).

<Alert type="info">
  Қорыта айтқанда, WEB-API-ге жіберілетін әрбір келесі сұрау алдыңғы жауаптан алынған 4
  тақырыптаманы қамтуы тиіс.
</Alert>

Бастапқы аутентификация жүйеде бар пайдаланушының электрондық пошта мекенжайы мен құпиясөзі арқылы орындалады. Ол үшін мына мекенжайға POST сұрауын жіберу қажет:

```bash
https://api.vadsro.eu/api/v1/auth/sign_in
```

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
```

Жауап ретінде мынадай хабар аламыз:

```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"}}
```

Бұл жауапта бізді мынадай тақырыптамалар қызықтырады:

| Тақырыптама    | Сипаттама                                                                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token` | Осы тақырыптаманың мәні әрбір сұрау үшін құпиясөз ретінде қолданылады. Мән әр сұрау сайын өзгеріп отырады.                                                                |
| `client`       | Бұл тақырыптама ағымдағы қосылым үшін бірегей. Бір мезгілде бірнеше белсенді сеанс жүргізуге мүмкіндік береді.                                                            |
| `expiry`       | Осы токеннің жарамдылық мерзімі бітетін уақыт. Әдепкі бойынша — алынған сәттен бастап 2 апта. Немесе мерзімінен бұрын тоқтату үшін SignOut. Келесі сұрау үшін қажет емес. |
| `uid`          | Пайдаланушыны сәйкестендіретін бірегей мән. Біздің жағдайда — электрондық пошта мекенжайы.                                                                                |
| `token-type`   | Қолданылатын токеннің типі.                                                                                                                                               |

Алдыңғы жауаптан алынған токенді пайдаланатын сұрау мысалы:

```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
```

Жауап ретінде мынадай хабар аламыз:

```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
}
```

Жұмысты аяқтау үшін SignOut процедурасын пайдалануға болады немесе соңғы сұраудан қажетті тақырыптамаларды сақтап қойып, токеннің жарамдылық мерзімі өтпеген болса, оларды келесі жолы қолдануға болады.

<Alert type="warning">
  Есіңізде болсын: сеансты аяқтамаған жағдайда соңғы токен екі апта бойы жарамды болып қала береді.
</Alert>

Сеансты аяқтау:

```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}
```

## Келесі қадамдар

Енді аутентификациядан өте алатын болғандықтан, API-дің негізгі ресурстарымен танысыңыз:

<Cards cols={2}>
  <Card
    icon="network"
    title="Ресурс жеткізушілер және тұтынушылар"
    description="Жеткізушілер иерархиясы мен олар қызмет көрсететін тұтынушылардың тізімін алу."
    link="/kk/api/v1/resource-providers-and-consumers"
  />
  <Card
    icon="gauge"
    title="Есепке алу тораптары"
    description="Есепке алу тораптарының тізімін алу және олардың физикалық сипаттамаларын оқу."
    link="/kk/api/v1/metering-units"
  />
  <Card
    icon="archive"
    title="Көрсеткіштер мұрағаттары"
    description="Арна көрсеткіштерін мұрағат түрі мен уақыт аралығы бойынша алу."
    link="/kk/api/v1/readings-archives"
  />
  <Card
    icon="bell"
    title="Оқиғалар және хабарлар"
    description="Құрылғы оқиғаларының мұрағаттарын және хабар кодтарының анықтамалығын оқу."
    link="/kk/api/v1/events-and-messages"
  />
</Cards>