شروع کار

این بخش، Web API پلتفرم را شرح می‌دهد که به‌صورت یک بستهٔ دادهٔ REST-API برای تبادل در قالب json پیاده‌سازی شده است.

کلیات

قالب انتقال داده Web API به‌صورت یک بستهٔ دادهٔ REST-API برای تبادل در قالب json پیاده‌سازی شده است.
رویهٔ احراز هویت احراز هویت بر پایهٔ توکنی است که به‌صورت پویا به‌روزرسانی می‌شود؛ این کار امنیت داده‌های دریافتی را تضمین می‌کند و از نشت توکن جلوگیری می‌کند.
قالب متغیرهای حاوی تاریخ و زمان Web API داده‌های از نوع تاریخ و زمان را با کدگذاری UNIX time یا POSIX time و در قالب UTC: 1613376963 بازمی‌گرداند. هنگام تبدیل Unix time به تاریخی خوانا، باید منطقهٔ زمانی را مشخص کنید.
صفحه‌بندی Web API قابلیت صفحه‌بندی را برای بارگذاری صفحه‌به‌صفحهٔ داده‌ها پیاده‌سازی می‌کند. از طریق پارامتر زیر ارسال می‌شود: page="page number" (page=1). تعداد رکوردهایی را که در پاسخ به درخواست بازگردانده می‌شوند می‌توان با پارامتر per_page تعیین کرد، اما نه بیش از 1000 رکورد.

URL پایه

همهٔ نمونه‌های این صفحات از URL پایهٔ زیر استفاده می‌کنند:

bash

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

احراز هویت

احراز هویت بر پایهٔ توکنی است که به‌صورت پویا به‌روزرسانی می‌شود. در عمل به این صورت است:

احراز هویت اولیه با ایمیل و گذرواژه‌ای انجام می‌شود که در سامانه وجود دارد و در پاسخ، یک توکن پویا و ویژگی‌های مرتبط با آن دریافت می‌شود.
ساختن درخواست موردنظر برای دریافت داده، به‌همراه افزودن توکن دریافت‌شده در گام پیشین به هدرهای درخواست HTTP.
ارسال درخواست به سرور. اگر درخواست به‌درستی ساخته شده باشد، سرور داده‌ها را در بدنهٔ پاسخ و توکنی جدید را در هدرهای پاسخ بازمی‌گرداند و توکن قدیمی نامعتبر می‌شود. با توکن جدید می‌توانیم گام پیشین را تکرار کنیم و به همین ترتیب ادامه دهیم.
پس از پایان کار، می‌توان آخرین توکن را پیش از تاریخ انقضای آن نامعتبر کرد (SignOut).

برای احراز هویت اولیه از ایمیل و گذرواژهٔ یک کاربر موجود استفاده می‌شود. برای این کار باید یک درخواست 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 استفاده کنید، یا هدرهای لازم را از آخرین درخواست ذخیره کنید و اگر طول عمر توکن به پایان نرسیده باشد، دفعهٔ بعد از آن‌ها استفاده کنید.

پایان دادن به نشست:

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}