Ishni boshlash

Ushbu boʻlimda platformaning Web API’si tavsiflanadi; u json formatida maʼlumot almashish uchun REST-API maʼlumot paketi koʻrinishida amalga oshirilgan.

Umumiy qoidalar

• Maʼlumotlarni uzatish formati Web API json formatida almashish uchun REST-API maʼlumot paketi koʻrinishida amalga oshirilgan.
• Autentifikatsiya tartibi Autentifikatsiya dinamik ravishda yangilanib turadigan tokenga asoslanadi; bu olinayotgan maʼlumotlar xavfsizligini kafolatlaydi va tokenning sizib chiqishiga yoʻl qoʻymaydi.
• Sana va vaqtni oʻz ichiga olgan oʻzgaruvchilar formati Web API «sana va vaqt» turidagi maʼlumotlarni UNIX time yoki POSIX time kodlashida UTC: 1613376963 formatida qaytaradi. Unix time qiymatini tushunarli sanaga aylantirishda vaqt mintaqasini koʻrsatish zarur.
• Sahifalash (pagination) Web API’da maʼlumotlarni sahifama-sahifa yuklash uchun sahifalash imkoniyati amalga oshirilgan. U parametr orqali uzatiladi: page="page number" (page=1). Soʻrovda qaytariladigan yozuvlar sonini per_page parametri orqali koʻrsatish mumkin, lekin 1000 yozuvdan oshmasligi kerak.

Bazaviy URL

Ushbu sahifalardagi barcha misollarda quyidagi bazaviy URL ishlatiladi:

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

Autentifikatsiya

Autentifikatsiya dinamik ravishda yangilanib turadigan tokenga asoslanadi. Amalda bu quyidagicha koʻrinadi:

• Birlamchi autentifikatsiya tizimda mavjud elektron pochta va parol yordamida bajariladi; javob sifatida dinamik token va u bilan bogʻliq atributlar olinadi.
• Maʼlumot olish uchun maqsadli soʻrov shakllantiriladi: oldingi qadamda olingan token HTTP soʻrovining sarlavhalariga qoʻshiladi.
• Soʻrov serverga yuboriladi. Agar soʻrov toʻgʻri shakllantirilgan boʻlsa, server javob tanasida maʼlumotlarni, javob sarlavhalarida esa yangi tokenni qaytaradi, eski token esa yaroqsiz boʻlib qoladi. Yangi token bilan oldingi qadamni takrorlash mumkin — va shu tariqa davom etadi.
• Ish yakunlangach, oxirgi tokenni amal qilish muddati tugashidan oldin yaroqsiz qilish mumkin (SignOut).

Birlamchi autentifikatsiyada tizimda mavjud foydalanuvchining elektron pochtasi va paroli ishlatiladi. Buning uchun quyidagi manzilga POST soʻrovini yuborish kerak:

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

Curl formatidagi soʻrov misoli:

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

Javob sifatida quyidagi xabarni olamiz:

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

Ushbu javobda bizni quyidagi sarlavhalar qiziqtiradi:

Oldingi javobdan olingan tokendan foydalanadigan soʻrov misoli:

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

Javob sifatida quyidagi xabarni olamiz:

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
}

Ishni yakunlash uchun SignOut protsedurasidan foydalanish yoki oxirgi soʻrovdan kerakli sarlavhalarni saqlab qoʻyib, tokenning amal qilish muddati tugamagan boʻlsa, ularni keyingi safar ishlatish mumkin.

Seansni yakunlash:

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}

Keyingi qadamlar

Endi autentifikatsiyadan oʻta olar ekansiz, API’ning asosiy resurslari bilan tanishing: