Tổng hợp một số chú ý khi code API

Bài đăng này đã không được cập nhật trong 6 năm

Khi phát triển API phía server để truyền tin Ajax với Javascript phía frontend , android hoặc Iphone. Vậy làm sao để thiết kế một API tốt ? Bài viết hôm nay , mình sẽ tổng hợp một số ý kiến khi thiết kế API

Các phương pháp theo versioning

Theo cách versioning thì có 4 cách . Với mỗi cách thì có ưu điểm và nhược điểm riêng, vì vậy tuỳ theo đặc trưng của service mà ta chọn cách hợp lý trong số đó

1. Customize , chèn thêm api-version vào http header

ex) x-api-version: 1

Với cách này, thông tin truyền đi mỗi lần khá ít.Nó khá là hiệu quả với service hầu như không phân tách giữa online và offline .Cả hai service của OAuth base system đều có tính tương thích rất cao.

Trong trường hợp không chỉ định version ở header , thì default sẽ sử dụng version mới nhất

Ví dụ : facebook graph

2. Trong http content-type

ex) application/com.xxxx.v2+json

Ví dụ sử dụng : github

3. Kiểu parameter

ex) /api/xxxx?api_version=1

Ví dụ cụ thể trong trường hợp sau khi login, session được sinh ra . Khi đó URL sẽ đơn giản kiểu

/api/session/create?id=foo&password=bar&api_version=1

nếu xác thực thành công, sẽ get session_token (chỉ có hiệu quả trong thời gian nhất định). Sau đó, vì áp dụng API version đã được lưu phía server nên không cần gửi thông tin đi kèm api_version từ phía client mà chỉ cần gửi mỗi thông tin key session_token.

Cách làm này có hiệu quả với service cần thiêt xác định trạng thái online or offline

4. Trong routing

ex) /api/v1/xxxx, /api/v2/xxxx

Ví dụ : foursquare

qiita

Tài liệu tham khảo

github developer blog

Không thể tạo file với mỗi version

Khi có xx.com/v1/xxx và xx.com/v2/xxx thì không thể tạo folder v1 và v2 Nếu đã tiến hành copy version , khi tạo v2 thì tính maintain bị hạ xuống .Ở thời điểm tạo v2, ta mới nhận ra 「a、cái này không thể maintain ・・・」.Và điều này với người lập trình viên hoàn toàn là thiết kế không ổn .

Tạo version theo nhánh hạn chế

Ví dụ : Khi có ５api controller 、trong trường hợp thay đổi nội dung chỉ 1 api controller, thì có thể thêm xử lý nhánh verion trong controller này

if ApiContext.api_version > 1
  { result: [{ name: 'foo', age: 20 }] }
else
  { result: { name: 'foo', age: 20 } }
end

Resource và controller

Routing có vai trò liên kết giữa resource và controller . Trong RubyOnRails nó chính là ActiveResource. Khi viết chúng ta hãy nhớ để sử sụng những gì có trong ActiveResource.

Trả lại kiểu HATEOAS

HATEOAS là gì ？

là viết tắt của Hypermedia As The Engine Of Application State。 Là mô hình kiến trúc mở rộng của pattern RESTful , tức là hành vi của REST client của bạn trên mỗi resource ,phụ thuộc vào những hypermedia trong mỗi resource.

Hypermedia là gì ？

Là việc lựa chọn việc tiếp theo từ liên kết của client , Hypermedia được coi là xương sống cho sự mềm dẻo và linh động và REST mang lại.

Hypermedia : Hyper(max )+ media(phương tiện cung cấp thông tin )

Định dạng cụ thể

Hiển thị quan hệ (relation) trong resouce thông qua link .

Hiển thị action có thể thực hiện tiếp theo thông qua link

xxx:{
  name: yyy,

  link: {
    rel: "self",
    url: "xxx.com/xxx/1"
  }
}

(Tài liệu tham khảo）

Hypermedia The Missing Element Spring article

REST: From GET to HATEOAS

Setting Web API giống với Web app HTML

Web API không có quá nhiều setting đặc biệt , xử lý tương đổi giống với web app.

Tuy nhiên về format hiển thị có khác nhau .

Bất cứ khi nào cũng nên sử sụng truyền tin kiểu SSL

Khi truyền tin , dù là thông tin nào cũng nên mã hoá theo kiểu SSL. Với thời đại chúng ta hiện nay, có thể truy cập Web API ở bất kì địa điểm công cộng nào. Các địa điểm này không nhất thiết là có sercuirity. Do đó , khi truyền tin mà không mã hoá thì sẽ rất dễ giả mạo thông tin

Một lợi điểm khác khi sử dụng SSL, có thể đơn giản xử lỷ xác thực bằng cách đảm bảo mã hoá. Bằng cách sử dụng access token, có thể rút ngắn xử lý chứng thực của mỗi request . Tuy nhiên , có chút lưu ý về trường hợp access không theo SSL trên URL của API . Không chuyển hướng access này đến API của SSL tương ứng . Thay vào đó, hãy show lỗi.Để đảm bảo cho client có setting không hợp lệ , gửi request đến điểm cuối không được mã hoá và để nó tránh bị redriect đến điểm cuối bị mã hoá