Helpex - Trao đổi & giúp đỡ Đăng nhập

8 mẹo để xây dựng một API

Tại Twelve Data, chúng tôi có nhiều kinh nghiệm trong việc tạo các API khác nhau. Một số mẹo này đã thu được thông qua các lỗi thực tế. Chúng tôi muốn chia sẻ với các bạn một số điều mà bản thân chúng tôi đang theo dõi để có thể dễ dàng hơn trong việc phát triển và duy trì sản phẩm của chính mình trong tương lai.

Phiên bản

Ngay từ khi bắt đầu phát triển API của bạn, bất kể nó có vẻ nhỏ như thế nào đối với bạn, hãy đưa phiên bản vào một tài khoản trong kiến ​​trúc của bạn. Nếu bạn không muốn viết mã để hỗ trợ lập phiên bản ngay lập tức, thì ít nhất hãy cố gắng thống nhất về cách bạn sẽ làm điều đó trong tương lai. Ít nhất, bạn cần phải chuẩn bị cho điều này.

Xác định thời hạn hỗ trợ cho các phiên bản kế thừa 

Cũng nên thỏa thuận trước ở giai đoạn thiết kế bạn sẽ duy trì các phiên bản cũ của API trong bao lâu, bao nhiêu phiên bản cùng lúc được coi là hoạt động, ai quyết định phiên bản đó bây giờ được coi là lỗi thời.

Nghĩ về người dùng ban đầu

Luôn nhớ rằng API của bạn có thể được sử dụng bởi các khách hàng ban đầu, những người không biết rằng bạn đã thay đổi điều gì đó trong các điểm cuối mới nhất của mình. Điều này đặc biệt đúng khi tạo API cho máy khách di động. Nếu bạn thay đổi bất kỳ logic nào bên trong điểm cuối, tốt hơn là bạn nên làm điều này bằng cách tạo một phiên bản mới của điểm cuối này hơn là thay đổi phiên bản hiện tại. Thay đổi điểm cuối hiện tại chỉ hợp lệ nếu nó không ảnh hưởng đến các tham số đến và đi. 

Duy trì cùng một kiểu trong Đường dẫn và Tham số

Đồng ý trước về cách bạn sẽ đặt tên cho các phương thức API, tham số đầu vào, v.v. Bạn có thể không tuân theo bất kỳ tiêu chuẩn được chấp nhận chung nào. Điều chính là trong hệ thống của bạn không có logic đặt tên khác nhau.

Ví dụ xấu

GET https://api.example.com/product/list - get list of products
GET https://api.example.com/promotions - get list of promotions


Như bạn có thể thấy từ ví dụ, trong một trường hợp, chúng tôi yêu cầu danh sách theo URL, trong đó đối tượng được đặt tên ở dạng số ít, theo sau là danh sách từ và trong ví dụ thứ hai, đối tượng chỉ được đặt tên ở dạng số nhiều. Nói chung, cả phương pháp thứ nhất và thứ hai đều có thể hiểu được ngay lập tức, nhưng trong trường hợp này, sẽ đúng nếu sử dụng ở mọi nơi theo định dạng số nhiều hoặc /.

Ví dụ tốt

GET https://api.example.org/products
GET https://api.example.org/offers


Sử dụng các tên giống nhau cho các tham số đầu vào

Các nhà phát triển sử dụng API của bạn sẽ thấy dễ dàng hơn nhiều nếu bạn duy trì tính nhất quán trong việc đặt tên cho các tham số API của mình. Điều này áp dụng cho các tham số lọc kết quả theo một cách nào đó hoặc, ví dụ, chỉ định thứ tự sắp xếp. 

Xác định cấu trúc phản hồi lỗi

Thiết kế API của bạn để tất cả các phương thức trả về lỗi theo cùng một kiểu và định dạng. Sẽ rất bất tiện nếu một số phương thức trả về mã HTTP 400 Bad request với phần thân trống, trong khi các phương thức khác trả về, ví dụ: 200 OK và phần thân phản hồi chứa thông tin về lỗi.

Tạo tài liệu tuyệt đẹp

Vâng, không có gì bí mật khi không ai thích viết tài liệu. Nhưng bạn phải viết nó. 

Tài liệu có thể được chia thành hai loại:

  1. Tài liệu nội bộ. Bạn nên mô tả tất cả các quy ước trong đó: kiểu mã, quy ước đặt tên cho các phương thức, tham số, định dạng phản hồi và yêu cầu, v.v. Loại tài liệu này, ít nhất, sẽ giúp các nhà phát triển mới bắt đầu nhanh hơn.
  2. Tài liệu công khai. Ngay cả khi một bộ phận lân cận sẽ sử dụng API của bạn, nó vẫn cần được mô tả. Ở đây bạn cần mô tả các định dạng phản hồi, cách xử lý lỗi đúng cách,… Sẽ rất tốt nếu bạn có tài liệu về các phương thức của API của mình.

Sẽ tốt nếu đối với mỗi điểm cuối bạn chỉ định:

  • Yêu cầu mẫu;
  • Một mô tả ngắn gọn về những gì xảy ra trong điểm cuối này;
  • Mô tả các tham số đầu vào (loại, tên, bắt buộc hay không);
  • Phản hồi mẫu;
  • Mô tả của từng trường trong phản hồi (tên, loại, mô tả). Bạn có thể viết tài liệu như vậy "bằng tay" hoặc sử dụng các phần mềm khác nhau để giúp giải quyết vấn đề này, chẳng hạn như swagger. Điều bắt buộc là phải luôn cập nhật tài liệu của bạn. Tốt hơn là nên theo dõi điều này liên tục vì sẽ rất khó đưa nó về đúng dạng của nó.

Xem ví dụ tài liệu tốt trong Dữ liệu mười hai

Kiểm tra

Bạn có thể nhận thấy rằng hầu hết tất cả các khuyến nghị của chúng tôi đều đề cập đến giai đoạn chuẩn bị. Và điều này cho thấy rằng, trước khi phát triển bất cứ thứ gì, cần phải dành thời gian cho việc thiết kế. Điều này sẽ giúp bạn tiết kiệm thời gian phát triển trong tương lai. Nó cũng sẽ giúp người dùng API tích hợp nó nhanh hơn.

13 hữu ích 0 bình luận 7.5k xem chia sẻ

Có thể bạn quan tâm

loading