Thiết kế RESTful API

Jun 14, 2022

1. API là gì

API được viết tắt của cụm từ Application Programming Interface (tạm dịch: Giao diện lập trình ứng dụng) là phương thức cho phép các thành phần của hệ thống phần mềm giao tiếp với nhau. Ví dụ Front-end và back-end của một hệ thống web hay ứng dụng di động hiện nay đều dùng đến API.

Untitled

2. Các giao thức và kiến trúc API

  • RPC

    RPC là Remote Procedural Call hay lệnh gọi thủ tục từ xa. Các RPC apis này thực hiện các hành động hay thủ tục ở trên máy chủ, và ngược lại máy chủ sẽ trả về dữ liệu theo một trong 2 ngôn ngữ: XML hoặc JSON.

  • SOAP

    Viết tắt của cụm từ Simple Object Access Protocol. Là một tiêu chuẩn giao tiếp được định nghĩa bởi tổ chức W3C sử dụng với ngôn ngữ XML được sử dụng phổ biến và rộng rãi trước đây. SOAP hỗ trợ nhiều giao thức kết nối Internet như HTTP, SMTP, TCP.

  • WebSocket

    Đây là một loại công nghệ mới giúp chúng ta tương tác và giao tiếp 2 chiều giữa trình duyệt người dùng với máy chủ. API này giúp các client gửi và nhận dữ liệu theo sự kiện (event-driven). (Ví dụ như: Facebook, Google Meet, các ứng dụng live streaming)

  • REST

    Là API phổ biến và linh hoạt nhất hiện nay, được viết tắt cho cụm từ REpresentational State Transfer. Kiến trúc REST dựa trên nền tảng kiến trúc client/server giúp tách biệt giữa front-end và back-end từ đó tạo ra sự linh hoạt trong việc phát triển cũng như triển khai. REST API có thể dùng với nhiều loại ngôn ngữ như XML, JSON, HTML,…

    Untitled

3. Các lợi ích của REST API

  • Có khả năng mở rộng

    Với khả năng tách biệt giữa client và server như đã nói ở phần trước, REST API giúp các nhà phát triển cũng như doanh nghiệp có thể đáp ứng nhiều nhu cầu trên các nền tảng khác nhau. Ví dụ không chỉ web mà còn sử dụng được trên Android, iOS

  • Dễ dàng tích hợp

    REST API có thể dễ dàng tích hợp các ứng dụng mới vào phần mềm hiện có. Từ đó làm tăng tốc độ phát triển vì không cần phải viết chức năng lại từ đầu.

  • Tính độc lập

    Một lợi ích khác của REST API là client và server độc lập với nhau. Nghĩa là, đội ngũ phát triển có thể làm việc độc lập ở các phần khác nhau của hệ thống phần mềm và thử nghiệm nhiều môi trường phần mềm nếu cần thiết

4. Các tiêu chí tạo nên một API tốt

  • Tuân theo chuẩn

    Có rất nhiều chuẩn để chúng ta có thể follow để tạo ra một API tốt. Hôm nay chúng ta sẽ nói về các ví dụ chính:

    1. HATEOAS

      Hypermedia as the Engine of Application State là một chuẩn khiến nghị cho các API RESTful. Với HATEOAS, các server sẽ cung cấp thông tin thông qua hypermedia (là một phần mở rộng của hypertext, có chứa các ảnh, video, âm thanh hay hyperlink). Dưới đây là một ví dụ về cấu trúc API HATEOAS.

      HTTP/1.1 200 OK
      
      {
          "account": {
              "account_number": 12345,
              "balance": {
                  "currency": "usd",
                  "value": 100.00
              },
              "links": {
                  "deposits": "/accounts/12345/deposits",
                  "withdrawals": "/accounts/12345/withdrawals",
                  "transfers": "/accounts/12345/transfers",
                  "close-requests": "/accounts/12345/close-requests"
              }
          }
      }
      
    2. JSend

      Đây là một chuẩn đơn giản hơn, và cũng dễ hiểu hơn. Bao gồm status của API và dữ liệu trả về.

      {
        "status": "success",
        "data": {
          "post": {
            "id": 1,
            "title": "A blog post",
            "body": "Some useful content"
          }
        }
      }
      
    3. HAL

      Hypertext Application Language cũng là một chuẩn để định nghĩa hypermedia (chẳng hạn các liên kết đến các nguồn tài nguyên bên ngoài như JSON hay XML). Chúng ta có 2 loại MIME type: là application/hal+xmlapplication/hal+json.

      {
        "_links": {
          "self": {
            "href": "http://example.com/api/book/hal-cookbook"
          },
          "next": {
            "href": "http://example.com/api/book/hal-case-study"
          },
          "prev": {
            "href": "http://example.com/api/book/json-and-beyond"
          },
          "first": {
            "href": "http://example.com/api/book/catalog"
          },
          "last": {
            "href": "http://example.com/api/book/upcoming-books"
          }
        },
        "_embedded": {
          "author": {
            "_links": {
              "self": {
                "href": "http://example.com/api/author/shahadat"
              }
            },
            "id": "shahadat",
            "name": "Shahadat Hossain Khan",
            "homepage": "http://author-example.com"
          }
        },
        "id": "hal-cookbook",
        "name": "HAL Cookbook"
      }
      
  • Hoạt động một cách ổn định

    Khi tạo ra API, các developer khác cũng sử dụng nó cho hệ thống phần mềm của họ. Vì vậy, việc tối ưu hoá performance API cũng ảnh hưởng tới các phần mềm khác. Vậy nên khi thiết kế API chúng ta cũng phải cần nghĩ đến số lượng người dùng có thể làm ảnh hưởng tới hiệu năng của API

  • Chuẩn hoá đầu ra, phân trang

    Mỗi người dùng khi sử dụng API không phải ai cũng muốn lấy ra tất cả dữ liệu, hay tất cả các thuộc tính. Vì vậy, việc phân trang cho API và chuẩn hoá các output field là vô cùng quan trọng và điều này cũng có thể cải thiện ít nhiều tới hiệu năng của API.

  • Có quy tắc đặt tên

    Khi chúng ta thiết kế REST API, những quy tắc đặt tên nên được tuân thủ

    1. Sử dụng các danh từ

      http://api.example.com/device-management/managed-devices 
      http://api.example.com/device-management/managed-devices/{device-id} 
      http://api.example.com/user-management/users
      http://api.example.com/user-management/users/{id}
      
    2. Nhất quán cách đặt tên giữa các API

      http://api.example.com/device-management
      http://api.example.com/device-management/managed-devices
      http://api.example.com/device-management/managed-devices/{id}
      http://api.example.com/device-management/managed-devices/{id}/scripts
      http://api.example.com/device-management/managed-devices/{id}/scripts/{id}
      
    3. Không sử dụng đuôi mở rộng file

      http://api.example.com/device-management/managed-devices.xml  /*Do not use it*/
      
      http://api.example.com/device-management/managed-devices 	/*This is correct URI*/
      
    4. Không sử dụng tên các hàm CRUD

      HTTP GET http://api.example.com/device-management/managed-devices  //Get all devices
      HTTP POST http://api.example.com/device-management/managed-devices  //Create new Device
      
      HTTP GET http://api.example.com/device-management/managed-devices/{id}  //Get device for given Id
      HTTP PUT http://api.example.com/device-management/managed-devices/{id}  //Update device for given Id
      HTTP DELETE http://api.example.com/device-management/managed-devices/{id}  //Delete device for given Id
      
    5. Sử dụng các query để filter trong URI

      http://api.example.com/device-management/managed-devices
      http://api.example.com/device-management/managed-devices?region=USA
      http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
      http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
      

5. Những điều nên tránh khi thiết kế API

  • Không đánh số phiên bản

    Khi phần mềm thay đổi, phiên bản phần mềm có thể được nâng cấp, và API cũng vậy. Việc không đánh số phiên bản (versioning) cho API sẽ khiến việc quản lý các chức năng mà API có thể thực hiện trở nên khó khăn hơn và người dùng cũng có thể sẽ gặp những rắc rối khi sử dụng API ở sai phiên bản. Để khắc phục điều này, ta có thể đánh số phiên bản vào thẳng URI của API ví dụ như https://example.com/v1/route hay https://example.com/v2/route hoặc sử dụng header theo dạng Accept: application/json;v=2.

  • Không có tài liệu

    Một hệ thống API rất cần thiết phải có một documentation rõ ràng. Mục đích là để giúp người dùng có thể hiểu được API mình muốn sử dụng. Tuy nhiên, để tài liệu API được chi tiết, ngoài phần mô tả tổng quan, tài liệu cần phải cover các mục như input, output, các mục tuỳ chọn hay bắt buộc, hay các response code có thể sẽ gặp phải.

  • Không được bảo mật/phân quyền

    Việc bảo mật hay phân quyền API là một trong những việc chúng ta nên cân nhắc làm đầu tiên khi thiết kế một API. Không có bảo mật API, hệ thống có khả năng rất cao sẽ bị tấn công, làm lộ các thông tin quan trọng hay thay đổi những dữ liệu không mong muốn.

  • Không có log

    Cuối cùng, API cũng cần những dòng log tốt. Không có log API, chúng ta sẽ rất khó để điều tra hay khắc phục các sự cố, lên kế hoạch cho các thay đổi mà người dùng cuối hay khách hàng mong muốn.

Great! You've successfully subscribed.
Great! Next, complete checkout for full access.
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.