Hướng dẫn tạo API (GP247)

Tài liệu này hướng dẫn thêm endpoint API trong hệ sinh thái GP247, gồm Front (khách hàng) và Core (quản trị).

Quy ước

• Prefix API Front: GP247_API_FRONT_PREFIX
• Prefix API Core: GP247_API_CORE_PREFIX
• Xác thực:
  • Front (khách): auth:customer-api kèm ability:
    • Lưu ý: Chỉ khả dụng khi cài gói gp247/shop.
    • Ability mặc định: config('gp247-config.api.auth.api_scope_user'), config('gp247-config.api.auth.api_scope_user_guest').
  • Core (admin): auth:admin-api kèm ability:
    • Ability mặc định: config('gp247-config.api.auth.api_scope_admin'), config('gp247-config.api.auth.api_scope_admin_supper').

Bạn có thể đăng ký route trong routes/web.php sử dụng các prefix trên. Các package cũng tự nạp route của chúng; thêm route mới cùng prefix là hợp lệ.

Front API công khai (không cần auth)

use Illuminate\Support\Facades\Route;

Route::group([
    'prefix' => GP247_API_FRONT_PREFIX,
], function () {
    // Public endpoints under Front API prefix
    // Example: GET /{FRONT_PREFIX}/banner/list
    Route::get('banner/list', 'App\\GP247\\Front\\Api\\FrontController@getBannerList');

    // Example: GET /{FRONT_PREFIX}/page/detail/{id}
    Route::get('page/detail/{id}', 'App\\GP247\\Front\\Api\\FrontController@getPageDetail');
});

Front Member API (yêu cầu gp247/shop)

use Illuminate\Support\Facades\Route;

$listAbility = [
    config('gp247-config.api.auth.api_scope_user'),
    config('gp247-config.api.auth.api_scope_user_guest'),
];

Route::group(['prefix' => GP247_API_FRONT_PREFIX], function () use ($listAbility) {
    // Login to issue access token for the customer guard
    Route::post('login', 'App\\GP247\\Shop\\Api\\Front\\MemberAuthController@login');

    Route::group([
        'middleware' => [
            'auth:customer-api',
            'ability:'.implode(',', $listAbility),
        ],
        'prefix' => 'member',
    ], function () {
        Route::get('order/list', 'App\\GP247\\Shop\\Api\\Front\\MemberAuthController@getOrderList');
        Route::get('order/detail/{id}', 'App\\GP247\\Shop\\Api\\Front\\MemberAuthController@getOrderDetail');

        // Logout revokes the current token
        Route::get('logout', 'App\\GP247\\Shop\\Api\\Front\\MemberAuthController@logout');
    });
});

Core Admin API

use Illuminate\Support\Facades\Route;

$listAbility = [
    config('gp247-config.api.auth.api_scope_admin'),
    config('gp247-config.api.auth.api_scope_admin_supper'),
];

Route::group([
    'prefix' => GP247_API_CORE_PREFIX,
], function () use ($listAbility) {
    // Admin login to obtain an access token
    Route::post('login', 'App\\GP247\\Core\\Api\\Controllers\\AdminAuthController@login');

    Route::group([
        'middleware' => [
            'auth:admin-api',
            'ability:'.implode(',', $listAbility),
        ],
    ], function () {
        Route::get('logout', 'App\\GP247\\Core\\Api\\Controllers\\AdminAuthController@logout');
        Route::get('info', 'App\\GP247\\Core\\Api\\Controllers\\AdminController@getInfo');
    });
});

Ghi chú

• Giữ nguyên tên guard và middleware đúng chữ hoa/thường.
• Khi phát hành token, gán đầy đủ ability cần thiết để middleware ability: hợp lệ.
• Nếu chưa cài gp247/shop, các endpoint yêu cầu auth:customer-api sẽ không hoạt động.