Getting Started with API

⚠ Lưu ý: Thông tin API chưa được cập nhật lên phiên bản mới nhất (v0.6.0). Sẽ có một số thông tin sai lệch với phiên bản hiện tại.

Ví dụ sử dụng API

• Một ví dụ đơn giản về cách sử dụng API của hệ thống được lưu trong thư mục public/apiExample.

• Yêu cầu:
  • Python 3.7 trở lên (chưa thử với 2.0 trở lên và 3.0 trở lên)
  • json package (pip install json)
  • requests package (hướng dẫn cài)
  • colorama package (pip install colorama)
• Chạy thử:
  1. Chắc chắn rằng máy chủ đang chạy bình thường
  2. Mở command prompt đối với windows hoặc bash đối với linux, sau đó đi tới tới thư mục public/apiExample (sử dụng lệnh cd)
  3. Nhập py main.py sau đó enter để chạy
  4. Khi được yêu cầu nhập hostaddress, điền địa chỉ máy chủ vào (ví dụ như localhost, 192.168.1.101)

Sử dụng API

HTTP/1.1

Tất cả dữ liệu truyền đều sử dụng giao thức Hypertext Transfer Protocol -- HTTP/1.1

Access Token

Sau khi đăng nhập, một token sẽ được tạo và lưu trong session của người dùng. Một số API liên quan tới chỉnh sửa thông tin sẽ yêu cầu phải có token này để được thực thi.

Đọc dữ liệu trả về của API

Dữ liệu trả về của API là kiểu dữ liệu JavaScript Object Notation (JSON).

Ví dụ về dữ liệu trả về của /api/info:

{
	"code": 0,
	"status": 200,
	"description": "Thành công!",
	"user": null,
	"data": {
		"id": "admin",
		"username": "admin",
		"name": "Admin"
	},
	"runtime": 0.001672983169555664
}

Trong đó:

Tên	Mô tả	Kiểu dữ liệu
code	Mã trả về (return code)	number
status	HTTP Status Code	number
description	Mô tả	string
user	Tên người dùng hiện tại	string
data	Dữ liệu trả về	array
runtime	Thời gian thực thi	number

Debugging Tool

Insomnia là công cụ dùng để debug REST API với rất nhiều tính năng hay mà các công cụ debug khác không có.

Lưu ý

Nếu library HTTP của bạn không hỗ trợ gửi cookie trong request

Trong trường hợp này bạn có thể gửi sessid nhận được sau khi đăng nhập tới API cần request thông qua phương thức GET hoặc POST

Nếu có thể bạn hãy cố gắng tìm cách để đính kèm cookie trong request hoặc chuyển sang dùng 1 library khác. Chỉ áp dụng cách thức trên trong trường hợp bất khả kháng vì bạn có thể làm lộ sessid khi gửi request qua giao thức không bảo mật HTTP.

Lỗi

"Bạn chưa đăng nhập" khi request một API

• Nguyên nhân:
  • Bạn chưa đăng nhập qua login API
  • Request tới API đấy chưa đính kèm cookie PHPSESSID
  • Sai sessid
  • Session đã hết hạn
• Cách khắc phục:
  • Đăng nhập qua login API
  • Đính kèm cookie trong request hoặc gửi query/form sessid trong request
  • Đăng nhập lại để lấy sessid mới

500 Internal Server Error

Khi gặp phải lỗi này, mong bạn gửi một báo cáo lỗi tại đây để mình có thể vá lỗi một cách nhanh nhất. Báo cáo lỗi bao gồm:

• Miêu tả lỗi
• Tệp bị lỗi
• Dòng bị lỗi trong tệp
• Các bước tiến hành để xảy ra lỗi (nếu có)

Ví dụ về một request gặp lỗi 500:

{
	"code": 2,
	"status": 500,
	"description": "Error Occurred: Division by zero",
	"user": null,
	"data": {
		"num": 2,
		"str": "Division by zero",
		"file": "login.php",
		"line": 12
	},
	"runtime": 0.002547025680541992
}