Mẹo phát triển API REST và thực tiễn tốt nhất - Phần 1

Giới thiệu và lập kế hoạch

Đây là bài đầu tiên trong một loạt ba bài đăng trên API REST.

• Phần 1: Giới thiệu và lập kế hoạch
• Phần 2: Gợi ý lược đồ, lỗi phổ biến và phản đối
• Phần 3: Mẹo về tài liệu và vượt ra khỏi những điều cơ bản

GIỚI THIỆU

API REST ở khắp mọi nơi những ngày này. Nếu bạn đang phát triển các ứng dụng hỗ trợ mạng, rất có thể bạn đã tiêu thụ ít nhất một trong mã của mình và rất có thể bạn đang đọc điều này bởi vì bạn sắp viết một trong những thứ của riêng bạn.

Bộ truyện này là gì và nó là gì

Loạt bài viết này không phải là một giới thiệu về REST. Nó giả định rằng bạn có một sự hiểu biết rõ ràng về REST là gì và mục tiêu của nó là gì. Nó cũng không có nghĩa là một bài viết Thực tiễn tốt nhất toàn diện về thiết kế và phát triển API Web. Có rất nhiều trong số đó đã có sẵn trực tuyến, và tôi sẽ đề nghị bạn đọc càng nhiều càng tốt.

Những gì nó chủ yếu là, là một danh sách các lỗi rất phổ biến và thường bị bỏ qua mà mọi người mắc phải khi thiết kế và triển khai API REST. Tôi biết, không chỉ bởi vì tôi đã gặp chúng ở những người khác API API, mà bởi vì tôi đã tạo ra một vài trong số chúng. :)

Tại sao điều này được viết

Trong một thế giới hoàn hảo, điều đầu tiên mà bất kỳ ai cũng nên làm ngay sau khi phát triển API REST, là viết một ứng dụng khách cho nó. Tôi không nói về một UI với danh sách các điểm cuối mà mọi người có thể gọi, thay vì một trường hợp sử dụng thực tế của API của bạn. Không có gì mở mắt hơn để tiết lộ sự thiếu hiệu quả của sáng tạo của bạn, hơn là thực sự phải sử dụng nó đúng cách. Tôi biết điều này, vì tôi đã phải làm điều đó hàng chục lần.

Tất nhiên thế giới của chúng ta không hoàn hảo và hầu hết thời gian, một nhà phát triển back-end phải chuyển sang những thứ khác sau khi họ hoàn thành việc triển khai API, nhưng chỉ đến khi người tiêu dùng API phải triệu tập anh ta trở lại để chuộc lỗi tội lỗi. Tôi cũng đã ở vị trí không vui đó nhiều lần, vì vậy, hy vọng rằng những sai lầm và mẹo của tôi sẽ giúp bạn tiết kiệm thời gian - để bạn giành chiến thắng phải quay lại mã API của mình cho đến khi hết giờ để thêm các tính năng mới.

LẬP KẾ HOẠCH

Hình ảnh vui lòng cung cấp bởi Dan Bickell

1. Trước khi bạn bắt đầu

Nghiên cứu nhiều tài liệu và sách thiết kế và phát triển API REST như bạn có thể tìm thấy! Tôi đã thắng đề cập đến những lời khuyên phổ biến ở đây, chẳng hạn như sử dụng danh từ thay cho URI động từ (ôi, tôi vừa mới làm v.v.), nhưng điều đó bởi vì tôi cho rằng bạn đã đọc về chúng ở nơi khác.

Xem xét lựa chọn thay thế

REST khá phổ biến như một mô hình, nhưng nó có nhiều hương vị. Trước khi tiếp tục, bạn nên xem càng nhiều càng tốt. Trong khi bạn đang ở đó, don không quên kiểm tra GraphQL - một cách tiếp cận hoàn toàn khác, nó không chỉ có vẻ tuyệt vời cho một số trường hợp sử dụng nhất định, mà còn được sử dụng bởi Facebook (người đã phát triển nó) và API v4 mới của GitHub.

Xem những gì người khác đã làm

Hãy xem và thực sự cố gắng sử dụng càng nhiều API phổ biến, từ các tổ chức có uy tín, càng tốt. Dưới đây là một số để giúp bạn bắt đầu: GitHub, Stripe, Twitter, PayPal

2. Quỹ

Don Patrick cho rằng API của bạn sẽ ở mức nhỏ - điều đó gần như không bao giờ xảy ra. Ngay cả khi bạn là người duy nhất sử dụng nó cho ứng dụng khách của riêng bạn, bạn sẽ sớm cần thêm điểm cuối, phân trang, phân tích, chế độ kiểm tra và biết những gì khác, và ngay cả trước khi ứng dụng của bạn trở nên phổ biến và người khác bắt đầu yêu cầu quyền truy cập vào API của bạn

OK - có thể đó là một đoạn đường dài; nhưng vì nó thường xảy ra trong quá trình phát triển phần mềm, nếu bạn không đặt nền tảng vững chắc từ sớm, bạn sẽ phải trả giá đắt cho nó trong thời gian dài. Vì các API cần nhất quán để có thể dễ dàng tiêu thụ, nên việc cố gắng thêm các tính năng cho chúng bằng cách sử dụng băng keo won won chỉ khiến mọi thứ trở nên khó khăn hơn cho bạn, nhưng đối với khách hàng của bạn.

Hơn nữa, bạn càng giỏi trong việc giữ mọi thứ sạch sẽ, thì càng mất ít thời gian để hoàn thành chúng và khá sớm

3. Đặc điểm kỹ thuật

Nói về một nền tảng vững chắc; hãy thử tạo đặc tả cho API của bạn trước khi thực sự bắt đầu viết mã. Tôi biết điều này nghe có vẻ nhàm chán nếu bạn đã thực hiện nó trước đây, nhưng về lâu dài nó sẽ giúp bạn tiết kiệm rất nhiều thời gian và rắc rối.

Thông số kỹ thuật OpenAPI (OAS - trước đây là Swagger) dường như là cách phổ biến nhất hiện nay, vì ngày càng có nhiều tổ chức và giải pháp thay thế đang hội tụ về nó. Ngoài ra, Postman là một môi trường phát triển API tuyệt vời nhưng nó chỉ miễn phí cho các cá nhân hoặc nhóm nhỏ các nhà phát triển.

Tôi thực sự khuyên bạn không nên bỏ qua mẹo này, trừ khi bạn đang phát triển một API nội bộ nhỏ mà chỉ bạn sẽ tiêu thụ.

4. Phiên bản

Tôi đã thắng tập trung vào các cách tiếp cận phiên bản khác nhau trong bài viết này, vì có nhiều tài nguyên chuyên dụng về chủ đề này trực tuyến. Tôi sẽ chỉ cố gắng làm nổi bật tầm quan trọng của việc bạn chọn một cách tiếp cận phiên bản mạnh mẽ và tuân theo tôn giáo. Tôi cũng sẽ trình bày một cách tiếp cận đã phục vụ tôi tốt trong những năm qua.

Tại sao nó lại quan trọng

Cách tiếp cận phiên bản mạnh mẽ mang đến sự an tâm cho người tiêu dùng của bạn (và do đó là người dùng cuối của bạn) bởi vì nó ngăn các thay đổi API làm xáo trộn chức năng của các ứng dụng khách hiện có. Ngay cả khi bản thân các ứng dụng khách được phát triển bởi cùng một nhà phát triển hoặc cùng một tổ chức với API, vẫn có nhiều tình huống mà các máy khách không dùng được vẫn có thể được sử dụng tại thời điểm có sẵn bản cập nhật API.

Một sự xuất hiện rất phổ biến của hiện tượng này là các ứng dụng máy khách hệ điều hành di động hoặc máy tính để bàn, nơi các nhà phát triển hiếm khi kiểm soát hoàn toàn chu kỳ cập nhật. Cho dù cơ chế cập nhật ứng dụng khách của bạn tốt và tự động đến mức nào, bạn gần như không bao giờ có thể chắc chắn 100% rằng người dùng của bạn đang chạy phiên bản mới nhất của ứng dụng khách.

iOS có cơ chế cập nhật tự động rất đáng tin cậy cho các ứng dụng được bật theo mặc định, tuy nhiên tùy thuộc vào sở thích và trạng thái mạng của người dùng, thiết bị của họ có thể không có cơ hội cập nhật ứng dụng khách của bạn vào lần chạy tiếp theo. Điều tương tự cũng đúng với các phiên bản Android mới hơn, trong khi các phiên bản cũ thậm chí còn có khả năng tụt hậu rất xa trong các bản cập nhật ứng dụng.

Mặt khác, các ứng dụng máy tính để bàn có thể hoặc không thể cung cấp cơ chế cập nhật tự động - nhưng đó là những ứng dụng được chọn trong hầu hết thời gian và luôn có các trường hợp (như môi trường doanh nghiệp) không cho phép cập nhật ngay lập tức. Ngay cả các ứng dụng khách trình duyệt cũng có thể (và trong hầu hết các trường hợp) nên được tách rời khỏi phần phụ trợ của chúng và do đó có chu kỳ phát hành hoàn toàn khác so với API.

Truyền đạt những thay đổi cho người tiêu dùng của bạn

Ngay cả khi bạn có API hoàn hảo với hệ thống phiên bản tốt nhất, tất cả đều không có nghĩa gì nếu người tiêu dùng của bạn không nhận thức được tiềm năng đầy đủ của nó. Truyền đạt các thay đổi và tính năng mới là rất quan trọng để người dùng của bạn có thể tận dụng tối đa lợi thế của chúng. Điều quan trọng hơn nữa là cảnh báo người dùng của bạn đủ sớm về các khía cạnh sẽ bị phản đối hoặc bị xóa, vì vậy họ có đủ thời gian để cập nhật, thử nghiệm và gửi các phiên bản mới của khách hàng.

Giữ một tài liệu cập nhật và phát hành các thay đổi chi tiết cho từng phiên bản là vô cùng quan trọng và phải là một phần của chu kỳ phát triển của bạn.

Cách tiếp cận phiên bản chính / phụ

Một cách tiếp cận phiên bản mà tôi đã đánh giá cao trong nhiều năm qua là một sơ đồ phiên bản chính / phụ. API của bạn được đặc trưng bởi một số phiên bản chính, mà (nếu bạn làm đúng) chỉ được cập nhật khi có những thay đổi vi phạm và một số phiên bản nhỏ, được cập nhật bất cứ khi nào có những bổ sung gia tăng nhỏ.

Nhìn từ một góc độ khác, mỗi phiên bản chính đảm bảo rằng cấu trúc của tài nguyên API và lược đồ giành được phá vỡ trong suốt vòng đời của nó, bất kể có bao nhiêu phiên bản nhỏ được phát hành trong thời gian đó. Các phiên bản nhỏ tương thích ngược.

Nó phổ biến cho phiên bản chính là một phần của URL cơ sở của API (ví dụ: https://api.myserver.com/v1/endpoint) và phiên bản phụ có thể được lựa chọn thông qua tiêu đề yêu cầu. Khi tiêu đề yêu cầu không được cung cấp, phiên bản nhỏ mới nhất sẽ được sử dụng. Có nhiều API phổ biến theo cách tiếp cận này, với API yêu thích của tôi là Stripe (sử dụng ngày phát hành cho các phiên bản nhỏ).

Mặc dù tôi sẽ đề cập đến cách tiếp cận này một lần nữa khi nói về các bản cập nhật cho API của bạn trong các phần sau, nhưng nó sẽ giúp bạn chọn hệ thống phiên bản chính thức phù hợp nhất với yêu cầu của bạn. Chỉ cần nhớ rằng một khi bạn làm, bạn sẽ phải cam kết với nó.

5. Kiểm tra

Điều này tốt khi bạn không sản xuất

Là một phần không thể thiếu trong quy trình phát triển phần mềm nói chung, kiểm tra là điều cần thiết cho API của bạn. Vì các API thường đóng vai trò là liên kết giữa một nguồn sự thật là máy chủ và một hoặc nhiều ứng dụng khách, nên chúng phải đáng tin cậy trong mọi trường hợp và không thể đủ khả năng để đi vào sản xuất bị hỏng theo bất kỳ cách nào. Hơn nữa, vì chúng thường được tiếp xúc với web và do đó dễ bị rủi ro với một số lượng lớn rủi ro, chúng phải được kiểm tra kỹ lưỡng cho một số lượng lớn các tình huống phổ biến và không phổ biến.

Kiểm tra thủ công bằng cách gọi các điểm cuối của bạn thông qua các công cụ như bảng điều khiển Swagger, Postman hoặc REST, chỉ có thể giúp bạn trong các bước phát triển đầu tiên, khi bạn vẫn đang thử nghiệm các tính năng cơ bản khác nhau. Việc duy trì một bộ các thử nghiệm tự động từ sớm tạo nên một thế giới khác biệt với chất lượng của sản phẩm hoàn chỉnh.

Do tính chất của chúng, API là ứng cử viên lý tưởng để thử nghiệm chức năng. Việc kiểm tra đơn vị thực hiện nội bộ của họ là rất quan trọng (giống như đối với bất kỳ phần mềm nào khác), nhưng theo tôi, chức năng kiểm tra API và việc so sánh nó với hộp đen cung cấp nhiều giá trị hơn cho thời gian bạn sẽ dành cho nó.

Duy trì cơ sở dữ liệu kiểm tra mà bạn có thể thiết lập và phá bỏ trong khi kiểm tra là một phần thiết yếu của quy trình. Tiếp tục thêm vào dữ liệu đã góp phần vào các vấn đề trong quá khứ (được quan sát trong quá trình phát triển hoặc được báo cáo bởi người tiêu dùng của bạn) và làm phong phú bộ thử nghiệm của bạn bằng các thử nghiệm hồi quy để đảm bảo rằng bạn đã thoát khỏi các lỗi đó một lần và mãi mãi.

Don không bao giờ cho rằng việc xác thực các tham số đầu vào của bạn đã hoàn tất cho đến khi bạn đã kiểm tra ngay cả những trường hợp kỳ lạ nhất (donith quên rằng ứng dụng khách của bạn có thể khá lỗi). Cuối cùng, đầu tư thời gian vào một cơ sở hạ tầng ghi nhật ký thích hợp để nắm bắt một vài lỗi thời gian chạy còn lại, quan sát hành vi của người tiêu dùng và sử dụng thông tin đó để tạo ra nhiều kịch bản thử nghiệm hơn nữa.

6. Triển khai

Như bạn có thể đã nhận thấy (hoặc sẽ chú ý khi bạn tiếp tục đọc), bài đăng này tập trung rất nhiều vào cách tạo API không phá vỡ mọi thứ. Tất nhiên, giai đoạn đáng sợ nhất để phá vỡ mọi thứ trong hầu hết các sản phẩm phần mềm là triển khai.

Trong hầu hết các trường hợp, nếu bạn đã thực hiện kiểm tra và phiên bản chính xác, khả năng gặp phải sự cố trong quá trình triển khai là rất thấp; tuy nhiên, đây là một số mẹo có thể giúp ích thêm.

Tách mọi thứ

Đây là một kịch bản rất phổ biến:

API của bạn cung cấp dữ liệu cho một vài khách hàng B2B được phát triển bởi các tổ chức bên ngoài, phục vụ một vài ứng dụng di động và ứng dụng web do chính tổ chức của bạn phát triển và là một phần không thể thiếu của ứng dụng máy chủ - cũng có thể truy cập qua web , cho mục đích quản trị.

Điều đó nghe có vẻ phức tạp, nhưng tôi đã thấy nó nhiều lần trong quá khứ với các biến thể đơn giản hơn hoặc phức tạp hơn. Điểm mấu chốt ở đây là API, mặc dù là nền tảng của một tổ chức, thường được kết hợp chặt chẽ với ít nhất một ứng dụng máy chủ có trách nhiệm khác.

Điều đó có nghĩa là khi có thời gian cập nhật ứng dụng máy chủ, nếu có sự cố xảy ra, rất có thể API cũng sẽ bị hỏng. Nếu điều đó xảy ra, API sẽ hạ bệ tất cả người tiêu dùng của nó cùng với nó, và cuối cùng người dùng cuối thì cơn thịnh nộ sẽ giáng xuống công ty.

Liên lạc với người dùng của bạn là điều cuối cùng bạn muốn

Một thiếu sót khác của khớp nối chặt chẽ trong bối cảnh này là chu kỳ phát hành của một ứng dụng ảnh hưởng đến tất cả các ứng dụng khác. Điều đó sẽ đòi hỏi lập kế hoạch phức tạp và phối hợp triển khai. Hơn nữa, nó không có ý nghĩa từ quan điểm kinh doanh (mỗi ứng dụng nên được phát hành trong thời gian tốt của riêng nó - mà không ảnh hưởng đến phần còn lại).

Nếu API của bạn và phần còn lại của ứng dụng được phát triển dưới dạng các mô-đun độc lập của cơ sở hạ tầng, thì tất cả những điều này sẽ biến mất. Ai đó có thể lập luận rằng có nhiều mô-đun riêng biệt hơn có nghĩa là nhiều điểm thất bại hơn, nhưng điều đó có thể được giải quyết bằng phiên bản và thử nghiệm thích hợp. Hơn nữa, ngay cả khi phiên bản API mới của bạn bị hỏng khi triển khai, nhóm của bạn sẽ là người đầu tiên biết. Trong trường hợp này, nếu không có gì tốt hơn có thể được thực hiện, bạn luôn có thể trì hoãn các bản phát hành của khách hàng của mình trong vài ngày cho đến khi bạn chắc chắn rằng mọi thứ đều hoạt động bình thường.

Một trường hợp nguy hiểm mà bạn phải đề phòng với việc kiểm tra nghiêm ngặt là khi phiên bản mới của ứng dụng máy chủ của bạn phá vỡ phiên bản API hiện có của bạn. Một lần nữa, cách duy nhất để tránh điều này là (tất nhiên) thông qua một quy trình phát triển nghiêm ngặt với phiên bản và thử nghiệm thích hợp. Đối xử với tất cả các phần của cơ sở hạ tầng của bạn như các mô-đun riêng biệt khuyến khích cách tiếp cận đó hơn nữa.

7. (Duyên dáng) Khấu hao

Tại một số thời điểm, khi ứng dụng của bạn đáo hạn, không thể tránh khỏi việc bạn sẽ phải từ chối phiên bản API chính hiện tại của mình để ủng hộ một phiên bản mới. Các ứng dụng khách vẫn đang được phát triển cũng sẽ phải nâng cấp lên phiên bản mới, nhưng điều đó có thể mất thời gian.

Hơn nữa, có những trường hợp ngay cả hành động ngay lập tức từ các nhà phát triển không có nghĩa là cập nhật ngay lập tức cho các ứng dụng khách. Mặc dù các phiên bản cập nhật của ứng dụng web có thể được cung cấp cho người dùng cuối ngay khi chúng được phát hành, các phiên bản cũ hơn của ứng dụng di động và hệ điều hành gốc có xu hướng tồn tại trong một thời gian dài. Một số người dùng không thực sự hiểu (hoặc thậm chí không biết) quá trình cập nhật ứng dụng trên điện thoại hoặc máy tính của họ. Nếu những ứng dụng đó đột nhiên bắt đầu gặp trục trặc, phản hồi của người dùng có thể là ngừng sử dụng chúng.

Không dùng phiên bản API chính không có nghĩa là gián đoạn dịch vụ. Phiên bản không dùng nữa sẽ tiếp tục hoạt động chính xác như đã làm trong một khoảng thời gian (càng lâu càng tốt) sẽ được truyền đạt rõ ràng và lặp lại (khi gần hết) cho người tiêu dùng của bạn. Lý tưởng nhất là các phiên bản API cũ hơn của bạn sẽ không bao giờ ngừng hoạt động, trừ khi chúng gây rủi ro bảo mật hoặc gây ra tác hại cho phần phụ trợ của bạn.

8. Thực hành tốt thường bị bỏ qua

Bạn có thể sử dụng các hình thức số nhiều hoặc số ít cho các tài nguyên, nhưng không phải cả hai

/ xe cũng ổn và xe cũng vậy, nhưng bạn có thể sử dụng cả hai. Chọn một hình thức và tuân theo nó trong suốt API của bạn. Nếu bạn không tôn trọng, bạn sẽ gây nhầm lẫn cho người tiêu dùng và thậm chí có thể là nhà phát triển của chính bạn hoặc chính bạn trong tương lai.

Trả về các đối tượng được cập nhật trong các phản hồi PUT và PATCH

Sau khi yêu cầu thành công thông qua các động từ PUT hoặc PATCH, khách hàng thường cần biết trạng thái của tài nguyên được cập nhật. Vì nó có khả năng nhiều khách hàng có thể cập nhật cùng một lúc, đây là cách duy nhất để thông báo cho mỗi người về trạng thái của tài nguyên tại thời điểm cập nhật diễn ra.

Bánh quy và PHPSESSIONID

Điều này rất phổ biến trong các ứng dụng do PHP phát triển. API sử dụng mã thông báo xác thực tùy chỉnh của riêng mình, nhưng không biết đến nhà phát triển sử dụng xử lý phiên mặc định PHP PHP, tất cả các phản hồi cũng bao gồm cookie PHPSESSIONID đáng sợ! Điều này gây ra tất cả các loại lỗi trong thời gian dài, bởi vì không ai (kể cả nhà phát triển) được thông báo về cookie, vì không ai nghĩ rằng họ đặt nó ở đó.

Cookies, nói chung, không bị cấm rõ ràng bởi REST. Chúng có thể gây rắc rối nếu được sử dụng không chính xác (ví dụ: nếu bạn cố truy cập một tên miền riêng cũng được cấp phép thông qua cơ chế API của bạn), nhưng chúng không bị cấm bởi bất kỳ đặc điểm kỹ thuật nào. Tuy nhiên, điều cần tránh là sử dụng nhiều hơn một hình thức xác thực cùng một lúc.

Về xử lý phiên PHP PHP, bạn không bao giờ nên dựa vào cách tiếp cận cookie PHP mặc định cho API của mình, trừ khi bạn muốn cookie PHPSESSIONID hoạt động như mã thông báo xác thực API API của bạn (mà tôi không khuyên dùng bất kỳ cách nào!). Lời khuyên của tôi sẽ là thực hiện một cơ chế xử lý phiên tùy chỉnh thực hiện phương thức xác thực ưa thích của bạn.

Don Tiết lộ lỗi nội bộ hoặc chi tiết thực hiện

Trong những năm qua, tôi đã thấy điều này trong vô số lần, ngay cả trong các API phổ biến của các công ty lớn. Nó không hay để lộ các lỗi nội bộ (như SQL) trong các phản hồi của bạn! Tìm một cách đáng tin cậy để ghi nhật ký để tham khảo trong tương lai, nhưng dịch chúng sang 500 chung - Lỗi máy chủ nội bộ trong các phản hồi API của bạn.

Các xkcd bắt buộc - luôn luôn có liên quan.

Đây là một trong những điều đầu tiên bạn nên làm sớm trong quá trình phát triển. Bảo mật phải là mối quan tâm hàng đầu đối với một dịch vụ được đưa ra trên web.

Đây là bài đầu tiên trong một loạt ba bài đăng trên API REST.

Bạn có thể đọc phần tiếp theo ở đây:
Phần 2: Gợi ý lược đồ, lỗi phổ biến và phản đối