Ra mắt API AppGini v1 - Giải pháp tích hợp ứng dụng di động và hệ thống khác

[admin]

Tiêu đề: Ra mắt API AppGini v1 - Giải pháp tích hợp ứng dụng di động và hệ thống khác

Chào cộng đồng AppGini Việt Nam,

Mình rất vui được chia sẻ một dự án mà mình đã phát triển nhằm mở rộng khả năng tích hợp của AppGini với các ứng dụng bên ngoài, đặc biệt là ứng dụng di động hoặc các hệ thống khác. Đây là phiên bản API v1, được xây dựng dựa trên PHP, MySQL, và sử dụng JWT (JSON Web Token) để xác thực an toàn.

Mục đích:
API này cung cấp một giao diện RESTful để tương tác với cơ sở dữ liệu AppGini của bạn, bao gồm các chức năng:

Đăng nhập người dùng AppGini và cấp JWT.
Thực hiện các thao tác CRUD (Create, Read, Update, Delete) trên dữ liệu bảng.
Tích hợp hệ thống quyền hạn của AppGini (dựa trên quyền người dùng và nhóm).
Bảo mật bằng API Key và JWT.
Tính năng chính:

Xác thực người dùng:
Sử dụng tên người dùng và mật khẩu AppGini để đăng nhập.
Tạo và trả về JWT để các yêu cầu API sau này được xác thực.
Kiểm tra trạng thái isApproved và isBanned của người dùng.

API Key Bảo mật:
Mỗi yêu cầu đến API api.php đều phải kèm theo một X-API-KEY được định nghĩa trong config.php, cung cấp một lớp bảo mật cơ bản cho ứng dụng của bạn.

Hỗ trợ CRUD:
GET: Lấy dữ liệu từ một bảng (có thể lấy tất cả hoặc một bản ghi theo ID). Áp dụng bộ lọc quyền PERM_OWNER và PERM_GROUP của AppGini.
POST: Thêm bản ghi mới vào một bảng. Tự động gán owner_memberID nếu cấu hình.
PUT: Cập nhật bản ghi hiện có theo ID.
DELETE: Xóa bản ghi theo ID.

Tích hợp hệ thống quyền hạn AppGini:
API tự động kiểm tra quyền allowInsert, allowView, allowEdit, allowDelete của người dùng hoặc nhóm cho từng bảng dựa trên các bảng membership_userpermissions và membership_grouppermissions.
Lọc dữ liệu GET và kiểm tra quyền CRUD dựa trên PERM_ALL, PERM_GROUP, PERM_OWNER.

Cấu hình linh hoạt:
Dễ dàng cấu hình thông tin cơ sở dữ liệu, JWT Secret Key, thời gian hết hạn token và API Key trong file config.php.

Cấu trúc thư mục và cài đặt:

Để sử dụng API này, bạn cần tạo một thư mục mới trong thư mục gốc của dự án AppGini của mình (ví dụ: your-appgini-project/api/v1/) và sao chép tất cả các file sau vào đó:

Mã Chọn Mở rộng

your-appgini-project/
├── admin/
├── images/
├── hooks/
├── api/v1/
│   ├── api.php
│   ├── auth.php
│   ├── config.php
│   ├── db_connection.php
│   ├── login.php
│   └── permissions.php
└── ... (các file AppGini khác)

Các file chính và chức năng:

config.php: Chứa các hằng số cấu hình quan trọng như thông tin kết nối DB, JWT_SECRET_KEY, API_KEY, và các tên bảng/mã quyền của AppGini. Quan trọng: Hãy thay đổi các giá trị mặc định cho DB_PASSWORD, JWT_SECRET_KEY, và API_KEY thành các chuỗi mạnh và duy nhất của bạn!

db_connection.php: Xử lý việc kết nối đến cơ sở dữ liệu MySQL và cung cấp các hàm tiện ích như respondWithError() và decodeJwt(). Lưu ý: Hàm decodeJwt() là một triển khai JWT cơ bản và không bao gồm đầy đủ các bước xác minh chữ ký. Trong môi trường PRODUCTION, bạn nên sử dụng thư viện JWT của bên thứ ba đáng tin cậy (ví dụ: composer require firebase/php-jwt) để giải mã và xác minh token.

auth.php: Chứa logic xác thực người dùng AppGini (loginUser()) và tạo/giải mã JWT. Nó cũng mô phỏng hàm password_match() của AppGini để kiểm tra mật khẩu.

permissions.php: Xử lý tất cả logic liên quan đến quyền hạn của AppGini. Bao gồm các hàm getUserTablePermissions(), checkPermission(), getOwnershipWhereClause(), và getOwnerFieldName(). Bạn cần tùy chỉnh hàm getOwnerFieldName() để ánh xạ đúng cột ID chủ sở hữu cho các bảng của bạn.

login.php: Endpoint để xử lý yêu cầu đăng nhập, xác thực thông tin người dùng và trả về JWT. Chỉ chấp nhận phương thức POST.

api.php: Endpoint chính cho các yêu cầu CRUD. Nó xác thực X-API-KEY, JWT, kiểm tra quyền của người dùng và thực hiện các thao tác trên cơ sở dữ liệu.

Cách dùng và thử nghiệm:

Bạn có thể dễ dàng kiểm tra API này bằng cách mở file test_api_v1.html trên trình duyệt của mình.

Sao chép test_api_v1.html: Đặt file này ở bất kỳ đâu trên máy tính của bạn (không cần đặt trong thư mục dự án web).
Mở trên trình duyệt: Mở test_api_v1.html bằng trình duyệt Chrome hoặc bất kỳ trình duyệt hiện đại nào.
Cấu hình API:
URL gốc API: Nhập URL mà bạn đã đặt các file API PHP của mình (ví dụ: http://localhost/api/v1).
API Key: Nhập API_KEY mà bạn đã định nghĩa trong file config.php.
Đăng nhập:
Nhập tên người dùng và mật khẩu của một tài khoản AppGini hợp lệ.
Nhấn nút "Đăng nhập". Nếu thành công, bạn sẽ nhận được một JWT.
Gửi yêu cầu API:
Chọn phương thức HTTP (GET, POST, PUT, DELETE).
Nhập tên bảng (ví dụ: members, products).
Nếu là GET/PUT/DELETE một bản ghi cụ thể, nhập "ID bản ghi".
Đối với POST/PUT, nhập JSON body vào textarea.
Nhấn "Gửi yêu cầu". Phản hồi API sẽ hiển thị bên dưới.
Ví dụ về cách test_api_v1.html kết nối đến API:

File test_api_v1.html là một công cụ đơn giản dựa trên JavaScript để gửi các yêu cầu HTTP đến các endpoint login.php và api.php. Nó sẽ thêm X-API-KEY vào header và Authorization: Bearer <JWT_TOKEN> sau khi bạn đăng nhập thành công.

Lưu ý quan trọng:

Bảo mật: Đây là phiên bản khởi đầu. Để sử dụng trong môi trường production, hãy đảm bảo:
JWT_SECRET_KEY và API_KEY của bạn là RẤT MẠNH VÀ DUY NHẤT.
Cân nhắc sử dụng HTTPS trên server của bạn để mã hóa tất cả lưu lượng truy cập.
Nâng cấp hàm decodeJwt() để sử dụng thư viện JWT chính thức để xác minh chữ ký đầy đủ.
Thực hiện validation đầu vào nghiêm ngặt hơn cho tất cả dữ liệu nhận được từ người dùng để ngăn chặn các cuộc tấn công SQL Injection hoặc XSS (mặc dù prepared statements đã giảm thiểu SQL Injection).
Mở rộng: Bạn có thể mở rộng API này để hỗ trợ các chức năng phức tạp hơn như tìm kiếm nâng cao, phân trang, sắp xếp, hoặc tích hợp các trường lookup/cha-con của AppGini.
Tùy chỉnh getOwnerFieldName(): Hãy chắc chắn rằng bạn đã cập nhật hàm getOwnerFieldName() trong permissions.php với các tên bảng và cột chủ sở hữu chính xác từ cơ sở dữ liệu AppGini của bạn.
Hy vọng API này sẽ hữu ích cho cộng đồng và là một khởi đầu tốt để tích hợp AppGini với thế giới bên ngoài! Mọi phản hồi và đóng góp đều được hoan nghênh.