Tất tần tật về API

124837

Hiện nguyên lý REST và cấu trúc dữ liệu RESTful (Đọc thêm RESTful là gì)được biết đến rất rộng rãi trong giới lập trình, nhưng vẫn có nhiều người hay nhầm lẫn. Bản thân REST không phải là một loại công nghệ, mà là phương thức tạo API với nguyên lý tổ chức nhất định. Những nguyên lý này nhằm hướng dẫn lập trình viên tạo môi trường xử lý API request được toàn diện hơn.

Trong bài viết này, tôi sẽ giải thích một số phương thức phát triển RESTful ở góc nhìn toàn cảnh nhất, đồng thời làm rõ khái niệm REST APIs. Tôi sẽ tập trung vào câu hỏi “lập trình cái gì” hơn là “lập trình như thế nào”.

REST For Web Developers

REST là viết tắt của Representational State Transfer. Giải thích đơn giản, REST là một loạt hướng dẫn và dạng cấu trúc dùng cho việc chuyển đổi dữ liệu. Thông thường, REST hay được dùng cho ứng dụng web, nhưng cũng có thể làm việc được với dữ liệu phần mềm.

API là viết tắt của Application Programming Interface, phương thức kết nối với các thư viện và ứng dụng khác. Windows có nhiều API, và Twitter cũng có web API, tuy chúng thực hiện các chức năng khác nhau, với mục tiêu khác nhau.

Nhìn chung, RESTful API là những API đi theo cấu trúc REST.

Cấu trúc REST là gì?

Thật khó giải thích sao cho cụ thể. Tuy nhiên, vẫn có một số quy luật bất biến, như:

  • Sự nhất quán trong cả API
  • Tồn tại không trang thái (ví dụ, không có server-side session)
  • Sử dụng HTTP status code khi cần thiết
  • Sử dụng URL endpoint với logical hierarchy
  • Versioning trong URL chứ không phải trong HTTP header

Sẽ không có bất cứ hướng dẫn nào như W3C HTML5 spec, quá cụ thể đến mức dẫn đến nhầm lẫn, đặc biệt là các nhầm lẫn tai hại quanh thuật ngữ REST.

Hơn nữa, bạn không nhất thiết phải tuân theo những quy luật trên không sai một chữ (dù quả thật đó là những quy luật quan trọng của RESTful API hiện đại).

REST là một phương thức nhỏ gọn. Nên rất được ưa chuộng cho dữ liệu HTTP. Cũng vì vậy nên REST dần phổ biến trên web, và được xem là lựa chọn “số một” cho phát triển API.

Theo như  Vinay Sahni đã nói, “API chính là UI của lập trình viên.” Mọi thứ phải dể dùng, với trải nghiệm tốt. Và đây chính là mục tiêu RESTful APIs hướng đến.

Cần chú ý với RESTful APIs

Những tip dưới đây dành riêng cho API trong môi trường ứng dụng web. Đồng nghĩa rằng HTTP là bắt buộc, và dữ liệu API sẽ thường được host trên external server. Hãy xem thử RESTful API làm việc như thế nào bên phía người dùng API.

Người dùng API là lập trình viên web có thể build một script kết nối đến một external API server, rồi dữ liệu cần thiết sẽ chuyển sang HTTP. Lập trình viên khi đó có thể hiển thị dữ liệu lên website mà không cần đến truy cập cá nhân vào external server.

Nhìn chung, có bốn lệnh dùng để truy cập RESTful API:

  1. GET để truy vấn object
  2. POST để tạo object mới
  3. PUT để sửa đổi hoặc thay thế một object
  4. DELETE để loại bỏ một object

Mỗi phương thức trên phải được API call thông qua để gửi chỉ thị cho server phải làm gì.

Đại đa số web API chỉ cho phép GET request lấy dữ liệu khỏi một externer server. Authencation không bắt buộc, nhưng nên có khi ta cho phép các lệnh khá “nguy hiểm” như PUT hay DELETE.

Tuy nhiên, rất ít thấy RESTful API nào cho phép các lệnh này. Ví dụ như http://pokeapi.co/, Pokemon API database miễn phí, với lượng rate limit công khai kha khá (rate limit: người dùng bị giới hạn số kiểu API request thực hiện được), nhưng chỉ cho phép phương thức GET để truy cập tài nguyên. Trong “dân gian” ta hay gọi kiểu giới hạn này là consumption-only API.

Return type cũng rất quan trọng, và nên dồng nhất với tất cả tài nguyên. JSON cũng là một return type nổi tiếng, với online specs giải thích đúng cấu trúc dữ liệu.

RESTfull API dùng danh từ cho API object, và động từ để thực hiện hành vi lên những object này.

Truy cập API Resources

Public API thường truy cập được từ địa chỉ website trực tiếp. Nói cách khác, cấu trúc URL rất quan trọng, chỉ nên dùng cho API request.

Một số URL có thể bao gồm đường dẫn tiền tố như /v2/ cho phiên bản 2 cập nhật từ API trước đó; hay thấy ở những lập trình viên muốn giữ 1.x API, nhưng vẫn muốn cung cấp cấu trúc mới nhất.

Nên nhớ, return data ở endpoint sẽ thay đổi mạnh mẽ dựa vào phương thức HTTP. Ví dụ, GET trả nội dung, còn POST tạo nội dung mới. Request có thể chỉ đến cùng một endpoint, nhưng kết quả có thể rất khác.

Để hiểu rõ khái niệm này, các bạn có thể lên tìm nhiều ví dụ online khác. Ngoài Pokeapi, ta còn có:

Tự build API

Quá trình xây dựng một API riêng không dễ dàng, nhưng cũng không quá phức tạp như nhiều người nghĩ.

Mỗi API phải kết nối đến server để trả dữ liệu. Bạn không những phải viết code để làm điều đó, mà còn phải format return data nữa. Một số yêu cầu khác có thể gồm authentication rate limiting.

Hãy điểm qua một số nguyên lý cơ bản của cấu trúc API.

Build Endpoints

building endpoint là một phần quan trọng trong quá trình phát triển API. Khi tạo tài nguyên bạn sẽ muốn dùng danh từ đấy, dừng dùng động từ. Nói cách khác dữ liệu API phải trả kết quả là người, nơi chốn, hoặc “thứ” gì đó. Thông thường, bạn sẽ nhận một “thứ” với thuộc tính cụ thể (ví dụ như tweet và metadata).

Tên danh từ là một phần cực kỳ quan trọng khi phát triển API, dù rất khó học. Nên hãy cố gắng càng đơn giản càng tốt

Vấn đề đáng tranh cãi ở đây là danh từ số ít hay số nhiều. Nếu bạn đang tạo API Twitter, bạn nên có object group trước (như: tweet), rồi object item sau (như: tweet ID).

1

2

$ /tweet/15032934882934

$ /tweets/15032934882934

Trong trường hợp này, tôi cho rằng thể số ít sẽ dễ nhìn hơn, đặc biệt khi chỉ trả một tài nguyên.

Đặt Return Type

Một vấn đè quan trọng nữa là return type data. Đa số người dùng web trông chờ nội dung JSON, vậy đây có lẽ là lựa chọn tốt nhất bên cạnh XML. JSON chính là API return type nền tàng cho lập trình web.

Vẫn còn nhiều mặt về phát triển API không thể kể hết, nếu bạn chưa quen thuộc với API, hãy dành thời gian “vọc” trước một chút. Từ đó xem thử những lập trình viên khác làm việc với API như thế nào, và hy vọng bạn sẽ dần quan thuộc hơn với những yêu cầu của API.

Nếu chỉ mới biết về API, bạn có thể xem qua các tài liệu sau:

Tài liệu nghiên cứu

Luyện tập vẫn là cách lập trình nhanh nhất. Những lý thuyết đã qua kiểm chứng luôn đáng để bạn học hỏi, vì qua đó bạn có thể tranh luận với những lập trình viên khác và hiểu được nguyên lý đằng sau lý thuyết đó.

Kết nối với các API khác trước cũng là một cách học hỏi hay. Hãy tìm hiểu về các điểm cơ bản nhất của kết nối client-side, và từ đó bạn có thể chuyển sang phát triển API, tạo API riêng từ con số không.

Bạn có thể tham khảo một số tài liệu dưới nếu muốn đi theo con đường API này.

Sách

Bài viết

Techtalk via hongkiat

CHIA SẺ