Жұмысты бастау

Бұл бөлімде платформаның 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 пайдаланылады:

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

Аутентификация

Аутентификация динамикалық түрде жаңарып отыратын токенге негізделген. Іс жүзінде бұл былай жүзеге асады:

• Бастапқы аутентификация жүйеде бар электрондық пошта мекенжайы мен құпиясөз арқылы орындалады; жауап ретінде динамикалық токен және онымен байланысты атрибуттар алынады.
• Деректерді алуға арналған мақсатты сұрауды қалыптастыру: алдыңғы қадамда алынған токен HTTP сұрауының тақырыптамаларына қосылады.
• Сұрауды серверге жіберу. Сұрау дұрыс қалыптастырылған болса, сервер жауап денесінде деректерді, ал жауап тақырыптамаларында жаңа токенді қайтарады, ескі токен болса жарамсыз болып қалады. Жаңа токенмен алдыңғы қадамды қайталауға болады — және осылай жалғаса береді.
• Жұмыс аяқталған соң, соңғы токенді жарамдылық мерзімі өтпей тұрып жарамсыз етуге болады (SignOut).

Бастапқы аутентификация жүйеде бар пайдаланушының электрондық пошта мекенжайы мен құпиясөзі арқылы орындалады. Ол үшін мына мекенжайға POST сұрауын жіберу қажет:

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

Curl пішіміндегі сұрау мысалы:

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

Жауап ретінде мынадай хабар аламыз:

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

Бұл жауапта бізді мынадай тақырыптамалар қызықтырады:

Алдыңғы жауаптан алынған токенді пайдаланатын сұрау мысалы:

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

Жауап ретінде мынадай хабар аламыз:

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 процедурасын пайдалануға болады немесе соңғы сұраудан қажетті тақырыптамаларды сақтап қойып, токеннің жарамдылық мерзімі өтпеген болса, оларды келесі жолы қолдануға болады.

Сеансты аяқтау:

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-дің негізгі ресурстарымен танысыңыз: