20/01/2019, 18:32

Xây dựng API với Laravel

Với các bạn làm dự án mà yêu cầu chạy trên môi trường web và app ..., để đồng bộ hóa dữ liệu thì chúng ta sẽ cần xây dựng Api cho dự án của mình, bài viết này mình sẽ hướng dẫn mọi người xây dựng API đúng chuẩn RESTful với framework Laravel version 5.7, vì sử dụng framework Laravel nên mọi người ...

Với các bạn làm dự án mà yêu cầu chạy trên môi trường web và app ..., để đồng bộ hóa dữ liệu thì chúng ta sẽ cần xây dựng Api cho dự án của mình, bài viết này mình sẽ hướng dẫn mọi người xây dựng API đúng chuẩn RESTful với framework Laravel version 5.7, vì sử dụng framework Laravel nên mọi người nên tìm hiểu cơ bản về laravel trước khi đọc bài viết.

Để bắt đầu xây dựng API đầu tiền chúng ta sẽ đi tìm hiểu qua về HTTP request, HTTP request có tất cả 9 loại method , 2 loại được sử dụng phổ biến nhất là GET và POST

GET: được sử dụng để lấy thông tin từ sever theo URI đã cung cấp.

HEAD: giống với GET nhưng response trả về không có body, chỉ có header

POST: gửi thông tin tới sever thông qua các biểu mẫu http (đăng kí chả hạn ...)

PUT: ghi đè tất cả thông tin của đối tượng với những gì được gửi lên

PATCH: ghi đè các thông tin được thay đổi của đối tượng.

DELETE: xóa tài nguyên trên server.

CONNECT: thiết lập một kết nối tới server theo URI.

OPTIONS: mô tả các tùy chọn giao tiếp cho resource.

TRACE: thực hiện một bài test loop - back theo đường dẫn đến resource.

Phía trên mình đã giới thiệu qua về các method của HTTP request, giờ sẽ đi áp dụng vào router của laravel.

Viết Api thì mọi người sẽ khai báo router vào file routes/api.php thay vì sử dụng file routes/web.php.

Mình sẽ giải thích qua về các setting mặc cho file api.php trong laravel 1 chút

Url: những router được khai báo trong file này mặc định có prefix url là api (ví dụ: viblo.asia/api/products)
Middleware: mặc định sẽ được gán Middleware Group là api, tìm trong file app/Http/Kernel sẽ thấy 2 middleware thuộc Middleware Group: api là throttle (giới hạn request / time) và bindings (model binding).

Mọi người có thể tùy chỉnh giá trị mặc định này trong method mapApiRoutes trong file app/Providers/RouteServiceProvider.php

Tiếp theo để thực hiện các thao tác đơn giản như CRUD (Create, Read, Update, Delete) mình sẽ tạo các router

// Lấy danh sách sản phẩm
Route::get('products', 'Api[email protected]')->name('products.index');

// Lấy thông tin sản phẩm theo id
Route::get('products/{id}', 'Api[email protected]')->name('products.show');

// Thêm sản phẩm mới
Route::post('products', 'Api[email protected]')->name('products.store');

// Cập nhật thông tin sản phẩm theo id
# Sử dụng put nếu cập nhật toàn bộ các trường
Route::put('products/{id}', 'Api[email protected]')->name('products.update');
# Sử dụng patch nếu cập nhật 1 vài trường
Route::patch('products/{id}', 'Api[email protected]')->name('products.update');

// Xóa sản phẩm theo id
Route::delete('products/{id}', 'Api[email protected]')->name('products.destroy');

Mặc định router đã được gán middleware bindings, nếu muốn sử dụng model binding trong controller thì chúng ta sửa lại tham số trong router như sau:

Route::get('products/{product}', 'Api[email protected]')->name('products.show');

Route::put('products/{product}', 'Api[email protected]')->name('products.update');

Route::patch('products/{product}', 'Api[email protected]')->name('products.update');

Route::delete('products/{product}', 'Api[email protected]')->name('products.destroy');

Ngoài ra trong laravel cũng hỗ trợ chúng ta 1 cách khai báo ngắn gọn hơn

Route::apiResource('products', 'ApiProductController');

Nếu không muốn sử dụng toàn bộ method trong apiResource mọi người có thể chỉ định sử dụng 1 vài method bằng hàm only

Route::apiResource('products', 'ApiProductController')->only(['index', 'show']);

Hoặc nếu muốn loại bỏ đi 1 số method không dùng thì có thể sử dụng hàm except

Route::apiResource('products', 'ApiProductController')->except(['show', 'update']);

Tương ứng với các Router RESTful ở phía trên, đặc biệt nếu mọi người dùng method apiResource thì laravel cũng hỗ trợ chúng ta các method xử lí tương ứng trong controller

Để tạo ra Resource Controllers chúng ta chạy lệnh sau

php artisan make:controller Api/ProductController -api

FIle ProductController tạo ra sẽ như sau

<?php

namespace AppHttpControllersApi;

use IlluminateHttpRequest;
use AppHttpControllersController;

class ProductController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return IlluminateHttpResponse
     */
    public function index()
    {
        //
    }

    /**
     * Store a newly created resource in storage.
     *
     * @param  IlluminateHttpRequest  $request
     * @return IlluminateHttpResponse
     */
    public function store(Request $request)
    {
        //
    }

    /**
     * Display the specified resource.
     *
     * @param  int  $id
     * @return IlluminateHttpResponse
     */
    public function show($id)
    {
        //
    }

    /**
     * Update the specified resource in storage.
     *
     * @param  IlluminateHttpRequest  $request
     * @param  int  $id
     * @return IlluminateHttpResponse
     */
    public function update(Request $request, $id)
    {
        //
    }

    /**
     * Remove the specified resource from storage.
     *
     * @param  int  $id
     * @return IlluminateHttpResponse
     */
    public function destroy($id)
    {
        //
    }
}

Ngoài ra nếu muốn sử dụng model binding khi tạo Resource Controllers thì dùng lệnh bên dưới

php artisan make:controller Api/ProductController --api --model=Models/Product

FIle ProductController tạo ra sẽ như sau, mọi người để ý tham số của các phương thức show, update, destroy sẽ thay đổi 1 chút

<?php

namespace AppHttpControllersApi;

use AppModelsProduct;
use IlluminateHttpRequest;
use AppHttpControllersController;

class ProductController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return IlluminateHttpResponse
     */
    public function index()
    {
        //
    }

    /**
     * Store a newly created resource in storage.
     *
     * @param  IlluminateHttpRequest  $request
     * @return IlluminateHttpResponse
     */
    public function store(Request $request)
    {
        //
    }

    /**
     * Display the specified resource.
     *
     * @param  AppModelsProduct  $product
     * @return IlluminateHttpResponse
     */
    public function show(Product $product)
    {
        //
    }

    /**
     * Update the specified resource in storage.
     *
     * @param  IlluminateHttpRequest  $request
     * @param  AppModelsProduct  $product
     * @return IlluminateHttpResponse
     */
    public function update(Request $request, Product $product)
    {
        //
    }

    /**
     * Remove the specified resource from storage.
     *
     * @param  AppModelsProduct  $product
     * @return IlluminateHttpResponse
     */
    public function destroy(Product $product)
    {
        //
    }
}

Phía dưới mình có demo 1 đoạn code đơn giản trong controller kết hợp với model binding và route apiResource khi xây dựng API

 <?php

namespace AppHttpControllersApi;

use AppHttpControllersController;
use AppModelsProduct;
use IlluminateHttpRequest;

class ProductController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return Product[]|IlluminateDatabaseEloquentCollection
     */
    public function index()
    {
        return Product::all();
    }

    /**
     * Store a newly created resource in storage.
     *
     * @param Request $request
     * @return Product|IlluminateDatabaseEloquentModel
     */
    public function store(Request $request)
    {
        return Product::create($request->all());
    }

    /**
     * Display the specified resource.
     *
     * @param Product $product
     * @return Product
     */
    public function show(Product $product)
    {
        return $product;
    }

    /**
     * Update the specified resource in storage.
     *
     * @param Request $request
     * @param Product $product
     * @return bool
     */
    public function update(Request $request, Product $product)
    {
        return $product->update($request->all());
    }

    /**
     * Remove the specified resource from storage.
     *
     * @param Product $product
     * @throws Exception
     */
    public function destroy(Product $product)
    {
        $product->delete();
    }
}

Mặc định khi sử dụng router apiResource thì dữ liệu trả về sẽ tự động được chuyển sang kiểu JSON và sẽ có status tương ứng nên mọi người chỉ cần return dữ liệu ra là ok, còn nếu muốn tùy biến status trả về thì có thể tham khảo cách phía dưới của mình, phía dưới mình có sử dụng class IlluminateHttpResponse để lấy status thay vì fix giá trị vào ví dụ như HTTP_OK tương ứng sẽ là 200

<?php

namespace AppHttpControllers;

use AppModelsProduct;
use IlluminateHttpRequest;
use IlluminateHttpResponse;

class ProductController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return IlluminateHttpJsonResponse
     */
    public function index()
    {
        $products = Product::all();

        return response()->json($products, Response::HTTP_OK);
    }
}

Khi xây dựng API, bạn có thể cần transform dữ liệu từ controller trước khi trả về cho người dùng ứng dụng của bạn, laravel cũng đã hỗ trợ điều này với Eloquent Resources

Để tạo ra 1 class chuyển đổi chúng ta chạy lệnh sau

php artisan make:resource Product

File app/Http/Resources/Product.php sẽ có nội dung như sau

<?php

namespace AppHttpResources;

use IlluminateHttpResourcesJsonJsonResource;

class Product extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @param  IlluminateHttpRequest  $request
     * @return array
     */
    public function toArray($request)
    {
        return parent::toArray($request);
    }
}

Mình sẽ tùy chỉnh dữ liệu trả về là chỉ có title và price

<?php

namespace AppHttpResources;

use IlluminateHttpResourcesJsonJsonResource;

class Product extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @param  IlluminateHttpRequest  $request
     * @return array
     */
    public function toArray($request)
    {
        return [
            'title' => $this->title,
            'price' => $this->price,
        ];
    }
}

Ở controller thì mình sẽ sửa lại như sau

 <?php

namespace AppHttpControllersApi;

use AppHttpControllersController;
use AppModelsProduct;
use IlluminateHttpRequest;
use AppHttpResourcesProduct as ProductResource;

class ProductController extends Controller
{
    /**
     * Display a listing of the resource.
     *
     * @return Product[]|IlluminateDatabaseEloquentCollection
     */
    public function index()
    {
        $products = Product::all();
    
        return ProductResource::collection($products);
    }

    /**
     * Store a newly created resource in storage.
     *
     * @param Request $request
     * @return Product|IlluminateDatabaseEloquentModel
     */
    public function store(Request $request)
    {
        $product = Product::create($request->all());

        return new ProductResource($product);
    }

    /**
     * Display the specified resource.
     *
     * @param Product $product
     * @return Product
     */
    public function show(Product $product)
    {
        return new ProductResource($product);
    }

    /**
     * Update the specified resource in storage.
     *
     * @param Request $request
     * @param Product $product
     * @return bool
     */
    public function update(Request $request, Product $product)
    {
        $product = $product->update($request->all());

        return new ProductResource($product);
    }

    /**
     * Remove the specified resource from storage.
     *
     * @param Product $product
     * @throws Exception
     */
    public function destroy(Product $product)
    {
        $product->delete();
    }
}

Ngoài giới hạn dữ liệu trả về như title hay price, laravel cũng hỗ trợ rất nhiều thứ như thêm relationships, data ..., mọi người có thể đọc thêm tại đây https://laravel.com/docs/5.7/eloquent-resources

200: Ok. Mã cơ bản có ý nghĩa là thành công trong hoạt động.
201: Đối tượng được tạo, được dùng trong hàm store.
204: Không có nội dung trả về. Hoàn thành hoạt động nhưng sẽ không trả về nội dung gì.
206: Trả lại một phần nội dung, dùng khi sử dụng phân trang.
400: Lỗi. Đây là lỗi cơ bản khi không vượt qua được xác nhận yêu cầu từ server.
401: Unauthorized. Lỗi do yêu cầu authen.
403: Forbidden. Lỗi này người dùng vượt qua authen, nhưng không có quyền truy cập.
404: Not found. Không tìm thấy yêu cầu tương tứng.
500: Internal server error.
503: Service unavailable.

Hiện tại có 3 cơ chế Authorize chính:

HTTP Basic
JSON Web Token (JWT)
OAuth2

Tùy thuộc vào service của bạn, mà hãy chọn loại Authorize có mức độ phù hợp, cố gắng giữ nó càng đơn giản càng tốt.

Ai cũng biết việc viết API docs là cần thiết, tuy nhiên để có một API docs hoàn chỉnh cũng tiêu tốn kha khá thời gian. Nhất là trong lúc dự án gấp rút thì mọi người thường chỉ để API docs ở mức ... dùng được case chính.

API document là một phần tương tự như Unit Test vậy - lấy ngắn để nuôi dài.

Nếu không được chăm sóc kỹ, thì đến lúc maintain hoặc thay đổi spec thì hậu quả sẽ rất thảm khốc, dưới đây là một số lưu ý lúc viết docs:

Mô tả đầy đủ về params request: gồm những params nào, datatype, require hay optional.
Nên đưa ra các ví dụ về HTTP requests và responses với data chuẩn.
Cập nhật Docs thường xuyên, để sát nhất với API có bất cứ thay đổi gì.
Format, cú pháp cần phải nhất quán, mô tả rõ ràng, chính xác.

https://laravel.com/docs/5.7/routing
https://laravel.com/docs/5.7/eloquent-resources
https://laravel.com/docs/5.7/controllers

Bình luận về bài viết này

Vũ Văn Thanh

12 chủ đề

2597 bài viết

Xây dựng API với Laravel

Đăng ký nhận thông báo

HỖ TRỢ HỌC VIÊN

VỀ CODE24H

HỢP TÁC VÀ LIÊN KẾT

KẾT NỐI VỚI CHÚNG TÔI

TẢI ỨNG DỤNG TRÊN ĐIỆN THOẠI