Toidicode.com

Toidicode.com

BASIC TO ADVANCE

Bài 19: Xây dựng REST API với Express

Ở bài trước bài viết của MiniBlog đã có ảnh đại diện, nhưng dữ liệu vẫn chỉ hiện ra dưới dạng trang HTML. Tiếp tục với series, bài này mình sẽ giới thiệu với mọi người về cách xây dựng REST API với Express để frontend hay ứng dụng di động lấy được dữ liệu dạng JSON.

1. Thiết kế REST API.

REST API coi mỗi loại dữ liệu là một resource có URL riêng (danh từ số nhiều như /posts), còn làm gì với nó thì do HTTP method quyết định. Server trả JSON kèm status code đúng ý nghĩa, client chỉ cần đọc status code là biết thành công hay lỗi gì.

Bài này MiniBlog có ba endpoint:

  • GET /api/v1/posts: danh sách bài viết, trả 200.
  • GET /api/v1/posts/:slug: chi tiết một bài, 200 hoặc 404.
  • POST /api/v1/posts: tạo bài từ body JSON, trả 201 Created kèm header Location trỏ tới bài mới, dữ liệu sai thì 422.

Ngoài ra còn 400 (JSON sai cú pháp), 413 (body quá lớn, Bài 17) và 500. Dữ liệu luôn nằm trong key data, lỗi nằm trong message, nên sau này thêm thông tin phân trang (Bài 21) cạnh data cũng không làm hỏng client cũ.

Phần v1 là phiên bản API. Ứng dụng di động cũ có thể chạy nhiều năm không cập nhật, nên khi phải đổi cấu trúc JSON, chúng ta mount bản mới ở /api/v2 và giữ /api/v1 tới khi không còn ai dùng.

2. Controller và router cho API.

API dùng lại service và validator của Bài 14, chỉ khác ở controller: trả JSON thay vì render view.

- controllers/api/post-controller.js

import { validationResult, matchedData } from 'express-validator';
import * as postService from '../../services/post-service.js';

// Chỉ trả các trường client cần, đặt tên theo kiểu camelCase của JavaScript
function toJson(post) {
    return {
        id: post.id,
        title: post.title,
        slug: post.slug,
        content: post.content,
        cover: post.cover,
        authorId: post.author_id,
        publishedAt: post.published_at,
    };
}

// GET /api/v1/posts
export async function index(req, res) {
    res.json({ data: await postService.listPosts() });
}

// GET /api/v1/posts/:slug (không có bài thì service ném HttpError 404)
export async function show(req, res) {
    const post = await postService.getPostBySlug(req.params.slug);
    res.json({ data: toJson(post) });
}

// POST /api/v1/posts
export async function store(req, res) {
    const result = validationResult(req);
    if (!result.isEmpty()) {
        return res.status(422).json({
            message: 'Dữ liệu không hợp lệ',
            errors: result.formatWith((error) => error.msg).mapped(),
        });
    }
    // Chưa có xác thực nên bài chưa có tác giả (Bài 20 sẽ bắt buộc token)
    const slug = await postService.createPost(matchedData(req));
    const post = await postService.getPostBySlug(slug);
    res.status(201).location(`/api/v1/posts/${slug}`).json({ data: toJson(post) });
}

Trong đó:

  • toJson() chọn các trường trả về thay vì gửi nguyên hàng trong database, sau này thêm cột vào bảng cũng không vô tình lộ ra API.
  • formatWith() rút gọn mỗi lỗi của express-validator (Bài 11) thành câu thông báo, mapped() gom lỗi theo tên trường.
  • res.location() đặt header Location, res.status(201) báo đã tạo resource mới.

Router của phiên bản 1 dùng package cors (phần 5), các bạn cài trước:

npm install cors

- routes/api-v1.js

import express from 'express';
import cors from 'cors';
import * as postApi from '../controllers/api/post-controller.js';
import { postRules } from '../validators/post.js';
import { notFound } from '../middlewares/error-handler.js';

const router = express.Router();

// Chỉ frontend ở CORS_ORIGIN được đọc response (không khai báo thì tắt CORS)
router.use(cors({ origin: process.env.CORS_ORIGIN }));

router.get('/posts', postApi.index);
router.get('/posts/:slug', postApi.show);
router.post('/posts', postRules, postApi.store);

// URL /api/v1/... không có: báo 404 luôn, không chạy tiếp các middleware của trang web
router.use(notFound);

export default router;

notFound (Bài 7) đặt cuối router nên URL sai trong /api/v1 dừng ngay tại đây. Bản 2 sau này là một file routes/api-v2.js khác.

3. Mount API trước kiểm tra CSRF.

- app.js (đoạn thay đổi)

import apiV1Router from './routes/api-v1.js';

// ...
app.use(express.json({ limit: '50kb' }));

// REST API: đặt trước cookie, session và csrfProtection vì API không dùng cookie
app.use('/api/v1', apiV1Router);

app.use(methodOverride('_method'));

Request tới API không đi qua cookie-parser, session hay csrfProtection. Không cần token CSRF ở đây vì CSRF lợi dụng việc trình duyệt tự gửi cookie của nạn nhân, mà API không đọc cookie thì request giả mạo cũng không mang theo quyền gì. Điều này chỉ đúng khi API không xác thực bằng cookie: Bài 20 dùng token gửi trong header Authorization, trang của kẻ xấu không tự gắn header đó được.

Chú ý: Bài này chưa có xác thực nên ai cũng tạo được bài qua API (bài không có tác giả, không ai sửa được). Các bạn đừng deploy MiniBlog ở trạng thái này.

4. Status code và lỗi dạng JSON.

Error handler của Bài 7 chọn JSON hay HTML theo header Accept, nên trình duyệt mở thẳng URL API sẽ nhận trang HTML. Mình cho API luôn trả JSON:

- middlewares/error-handler.js (đoạn thay đổi)

    // API (/api/...) luôn trả JSON, trang web thì chọn theo header Accept
    if (req.originalUrl.startsWith('/api/') || req.accepts(['json', 'html']) === 'json') {
        return res.status(status).json({ message });
    }

Chạy npm run dev rồi thử đọc dữ liệu:

curl -s http://localhost:3000/api/v1/posts
# {"data":[{"id":2,"title":"Route trong Express 5","slug":"route-trong-express-5"},{"id":1,"title":"Những tính năng mới trong Express 5","slug":"nhung-tinh-nang-moi-trong-express-5"}]}
curl -s http://localhost:3000/api/v1/posts/route-trong-express-5
# {"data":{"id":2,"title":"Route trong Express 5","slug":"route-trong-express-5","content":"Route trong Express...","cover":null,"authorId":null,"publishedAt":"2026-11-15T07:38:44.000Z"}}
curl -s -w ' %{http_code}\n' http://localhost:3000/api/v1/posts/khong-co
# {"message":"Không tìm thấy bài viết"} 404

Tạo bài mới, thêm -i để xem cả status và header:

curl -s -i -H 'Content-Type: application/json' -d '{"title":"Xây dựng REST API với Express","content":"API trả dữ liệu JSON cho frontend và ứng dụng di động."}' http://localhost:3000/api/v1/posts
# HTTP/1.1 201 Created
# ...
# Location: /api/v1/posts/xay-dung-rest-api-voi-express
# Content-Type: application/json; charset=utf-8
# ...
# {"data":{"id":3,"title":"Xây dựng REST API với Express","slug":"xay-dung-rest-api-voi-express","content":"API trả dữ liệu JSON cho frontend và ứng dụng di động.","cover":null,"authorId":null,"publishedAt":"2026-11-15T07:38:47.000Z"}}

Dữ liệu sai thì nhận 422 cùng lỗi của từng trường, JSON hỏng thì express.json() báo 400:

curl -s -w ' %{http_code}\n' -H 'Content-Type: application/json' -d '{"title":"Xây dựng REST API với Express","content":"ngắn"}' http://localhost:3000/api/v1/posts
# {"message":"Dữ liệu không hợp lệ","errors":{"title":"Tiêu đề này đã có bài viết khác dùng","content":"Nội dung phải có ít nhất 20 ký tự"}} 422
curl -s -w ' %{http_code}\n' -H 'Content-Type: application/json' -d '{"title":' http://localhost:3000/api/v1/posts
# {"message":"Unexpected end of JSON input"} 400

Response của API không có Set-Cookie, đúng như mong muốn. Thử xong các bạn chạy npm run db:seed để xoá bài vừa tạo.

5. CORS cho frontend.

Như đã nói ở Bài 17, frontend chạy ở origin khác (VD: Vite ở http://localhost:5173) chỉ đọc được response khi API trả header CORS. Package cors (bản 2.8.6, có trong danh sách middleware của Express) lo việc này, origin được phép lấy từ biến CORS_ORIGIN. Các bạn thêm dòng CORS_ORIGIN=http://localhost:5173 vào .env và .env.example, rồi khởi động lại npm run dev để đọc lại .env.

origin là một chuỗi thì cors luôn gửi Access-Control-Allow-Origin bằng chuỗi đó, trình duyệt ở origin khác thấy không khớp sẽ chặn. Cần nhiều origin thì truyền mảng. Thiếu biến thì origin là undefined và cors không gửi header nào (tắt CORS), an toàn hơn cors() không option (cho mọi origin).

Request POST với Content-Type: application/json làm trình duyệt gửi trước một request OPTIONS (preflight) để hỏi server. Giả lập bằng curl:

curl -s -i -X OPTIONS -H 'Origin: http://localhost:5173' -H 'Access-Control-Request-Method: POST' -H 'Access-Control-Request-Headers: content-type' http://localhost:3000/api/v1/posts
# HTTP/1.1 204 No Content
# ...
# Access-Control-Allow-Origin: http://localhost:5173
# Vary: Origin, Access-Control-Request-Headers
# Access-Control-Allow-Methods: GET,HEAD,PUT,PATCH,POST,DELETE
# Access-Control-Allow-Headers: content-type
# ...

Thấy origin và header được phép, trình duyệt mới gửi request POST thật. Trang web của MiniBlog không có các header này vì cors chỉ gắn trong router API.

Code đầy đủ của MiniBlog sau bài này nằm ở tag bai-19 trên GitHub; các thay đổi của riêng bài này: so sánh bai-18...bai-19.

6. Lời kết.

Như vậy là chúng ta đã xây dựng REST API với Express cho MiniBlog: thiết kế URL theo resource, phiên bản /api/v1, trả JSON với status code đúng, validate dữ liệu và bật CORS cho frontend. API tạo bài vẫn đang mở cho mọi người, bài sau mình sẽ giới thiệu với mọi người về xác thực API bằng JWT trong Express để khoá nó lại.

Đăng ký nhận tin.

Chúng tôi chỉ gửi tối đa 2 lần trên 1 tháng. Tuyên bố không spam mail!

Vũ Thanh Tài

About author
The best way to learn is to share
Xem tất cả bài đăng

0 Comments

Bài viết chưa có ai bình luận, hãy là người đầu tiên đi bạn!

Bình luận

Captcha