Thoát khỏi việc đơn độc: Học cách cộng tác phát triển API với Người đưa thư

Phát triển API là một phần quan trọng khiến tôi yêu thích phần mềm. Cho dù đó là xây dựng các tiện ích tích hợp hay tạo API cho các ứng dụng web tách rời, thường chỉ có tôi và mã .

Hầu hết thời gian, tôi làm việc với tư cách là nhà phát triển API một mình. Đi một mình có những đặc quyền: quyết định nhanh chóng và toàn quyền kiểm soát. Nhưng đó là con dao hai lưỡi vì việc giữ mọi thứ trong đầu khiến việc giao việc và ủy quyền trở nên khó khăn. Và hoạt động solo sẽ hạn chế quy mô và độ phức tạp của các dự án mà tôi có thể thực hiện. Suy cho cùng, tôi chỉ là một người.

Người đưa thư là công cụ chính của tôi để làm việc với API — gửi yêu cầu, quản lý môi trường và chạy thử nghiệm. Tôi đã quen với quy trình làm việc solo của mình. Nhưng tôi bắt đầu tự hỏi: trong môi trường nhóm, Postman có thể cung cấp thêm những gì? Làm thế nào nó có thể tăng cường hợp tác và hợp lý hóa quy trình phát triển?

Để khám phá những câu hỏi này, tôi bắt đầu nghiên cứu một API mẫu mà tôi gọi là “X Nihilo”.

API ví dụ: X Nihilo

X Nihilo giúp bạn tạo các dòng tweet dài 280 ký tự dựa trên các thông số bạn lưu trữ hoặc gửi. Bạn cung cấp chủ đề, mục tiêu, mô tả về giọng điệu cần thực hiện và mô tả về khán giả. Đằng sau hậu trường, API sẽ gửi yêu cầu tới API của OpenAI để hoàn thành văn bản, điều này sẽ hỗ trợ tạo tweet.

Ngoài ra, bạn có thể lưu các chuỗi bạn sử dụng cho giai điệu và khán giả, sau đó sử dụng lại chúng trong các yêu cầu tweet tiếp theo.

Hãy cùng tìm hiểu quy trình làm việc dành cho nhà phát triển API cơ bản của tôi.

Làm việc một mình: quy trình làm việc một mình của tôi

Bước đầu tiên trong quy trình làm việc của tôi là thiết kế API và viết thông số OpenAPI. Trong Postman, tôi đã tạo một API mới và sau đó tôi bắt đầu định nghĩa API mới.

Sau một hồi suy nghĩ (và làm việc trực tiếp với ChatGPT, một công cụ tuyệt vời để tạo thông số OpenAPI ban đầu dựa trên mô tả của tôi), tôi đã viết thông số kỹ thuật của mình:

Với thông số kỹ thuật OpenAPI đã sẵn sàng, tôi đã đến được một ngã ba đường. Tôi có nên thiết lập một máy chủ mô phỏng và một số yêu cầu cũng như phản hồi mẫu để hiển thị giao diện khi tương tác với API này không? Hay tôi nên bắt đầu viết mã triển khai?

Với tư cách là nhà phát triển solo, tôi chỉ có thể là nhà sản xuất API hoặc người tiêu dùng API tại bất kỳ thời điểm nào. Vì vậy, tôi quyết định: không cần xây dựng mô hình - người tiêu dùng trong tôi sẽ phải đợi. Hãy viết một số mã!

Một lúc sau…

Sử dụng Node.js với Express và nói chuyện với cơ sở dữ liệu PostgreSQL, tôi đã triển khai API cơ bản của mình. Đây là danh sách tất cả mọi thứ tôi cần để xây dựng:

• POST /signin lấy username và password , xác thực dựa trên các bản ghi trong cơ sở dữ liệu và sau đó trả về JWT đã ký, có thể được sử dụng trong tất cả các yêu cầu tiếp theo.
• POST /generateTweet tạo một tweet dài 280 ký tự (tối đa). Nó cần một topic (chuỗi) và một goal (chuỗi). Nó cũng có một tone (chuỗi) hoặc một toneId (ID số nguyên của một âm được lưu trữ), cùng với một audience (chuỗi) hoặc một audienceId (ID số nguyên của một đối tượng được lưu trữ). Bất cứ khi nào chuỗi tone và/hoặc audience được cung cấp và API sẽ lưu chúng vào cơ sở dữ liệu.
• GET /tones trả về danh sách ID âm và chuỗi tương ứng. GET /audiences thực hiện tương tự đối với chuỗi đối tượng có thể sử dụng lại.
• DELETE /tones lấy ID âm và xóa bản ghi âm đó. DELETE /audiences thực hiện tương tự đối với các bản ghi đối tượng.

Sau khi quá trình triển khai ban đầu hoàn tất, đã đến lúc quay lại Postman để bắt đầu chạy một số yêu cầu.

Tạo một môi trường với các biến.

Đầu tiên, tôi tạo một môi trường mới có tên là “Thử nghiệm”. Tôi đã thêm các biến để lưu trữ root_url cùng với username và password hợp lệ.

Tạo một bộ sưu tập và một yêu cầu

Sau đó, tôi đã tạo một bộ sưu tập mới và thêm yêu cầu đầu tiên của mình: yêu cầu POST vào /signin để thử xác thực.

Với máy chủ API của tôi đang chạy trong cửa sổ terminal, tôi đã gửi yêu cầu đầu tiên của mình.

Thành công! Tôi đã nhận được mã thông báo mà tôi sẽ cần trong bất kỳ yêu cầu nào trong tương lai.

Tôi đã tạo một yêu cầu mới, lần này là để tạo một tweet.

Tôi đảm bảo đã đặt Ủy quyền để sử dụng “Mã thông báo mang” và tôi đã cung cấp mã thông báo mà tôi vừa nhận được từ yêu cầu trước đó.

Đây là phản hồi:

Nó hoạt động!

Tổng hợp phương pháp solo

Đó là cái nhìn sơ lược cơ bản về quy trình làm việc solo của tôi. Tất nhiên, tôi sẽ làm một số việc khác trong quá trình thực hiện:

• Viết tập lệnh yêu cầu trước để thực hiện yêu cầu /signin , sau đó đặt biến môi trường dựa trên mã thông báo trong phản hồi.
• Tạo yêu cầu cho tất cả các điểm cuối khác trong thông số OpenAPI.
• Viết bài kiểm tra cho từng điểm cuối, đảm bảo bao gồm các trường hợp khó khăn của tôi.

Nếu tôi làm việc một mình, quy trình làm việc cơ bản này sẽ giúp tôi tiến gần đến đích. Mặc dù điều đó không sao nhưng tôi biết rằng có lẽ tôi chỉ đang tìm hiểu sơ qua về các tính năng có sẵn trong Postman. Và tôi biết rằng tôi sẽ cần nhiều hơn thế từ Postman nếu tôi làm việc theo nhóm.

Khoảnh khắc aha: Tại sao nên cân nhắc Postman cho các nhóm?

Điều gì sẽ xảy ra nếu tôi không còn là nhà phát triển API solo cho X Nihilo nữa? Điều này có thể xảy ra do một số lý do:

• X Nihilo ngày càng phát triển về quy mô và độ phức tạp, và một nhà phát triển API duy nhất không còn đủ để hỗ trợ nó nữa.
• X Nihilo chỉ là một phần nhỏ trong dự án API lớn hơn có sự tham gia của nhiều nhà phát triển API hoặc thậm chí có thể là nhiều nhóm API.

Không phải tất cả các dự án API dành cho khách hàng của tôi đều là những dự án nhỏ mà tôi có thể tự xây dựng. Đôi khi, tôi cần phải tham gia nhóm xây dựng API. Tôi thậm chí có thể cần phải lãnh đạo nhóm API.

Khi điều đó xảy ra, tôi sẽ cần phải bỏ lại suy nghĩ solo của mình và bỏ lại cách làm việc một mình trong Postman. Điều đó thúc đẩy tôi xem xét các tính năng liên quan đến nhóm của Postman.

Khám phá các tính năng của nhóm (doanh nghiệp) của Postman

Postman có cấp độ miễn phí và cung cấp một số tính năng cộng tác hạn chế, có thể đủ nếu bạn là một nhóm nhỏ (nghĩa là không quá ba nhà phát triển). Người đưa thư có các tính năng bổ sung như một phần của cấp Enterprise Essentials. Đây là những điều tuyệt vời cho các nhóm API trong các tổ chức lớn hơn sử dụng Postman trên diện rộng.

Chia sẻ không gian làm việc

Không gian làm việc cho phép nhóm của bạn cộng tác trên nhiều dự án API. Điều này thật tuyệt nếu bạn có các nhóm khác nhau làm việc trên các API khác nhau nhưng các API đó tương tác với nhau (điều này thường xảy ra trong các tổ chức phần mềm lớn hơn).

Không gian làm việc là nơi tuyệt vời để cho phép cộng tác theo thời gian thực. Các thành viên trong nhóm có thể chỉnh sửa tài liệu API, làm việc cùng nhau trong việc tạo các yêu cầu hoặc viết bài kiểm tra và xây dựng một máy chủ mô phỏng mà toàn bộ nhóm có thể sử dụng. Khi thực hiện chỉnh sửa, chúng sẽ được đồng bộ hóa với toàn bộ nhóm theo thời gian thực.

Kiểm soát phiên bản

Mặc dù tôi quan tâm đến việc kiểm soát phiên bản cho mã của mình, nhưng với tư cách là nhà phát triển API solo, tôi không quan tâm nhiều đến việc kiểm soát phiên bản của các bộ sưu tập hoặc môi trường Postman của mình. Nếu tôi thay đổi điều gì đó (sửa đổi yêu cầu, cập nhật thử nghiệm, xóa biến môi trường), tôi là người duy nhất bị ảnh hưởng. Không có gì to tát.

Khi bạn làm việc theo nhóm, bạn chắc chắn muốn biết khi nào mọi thứ thay đổi. Và đôi khi bạn cần khôi phục các thay đổi. May mắn thay, đối với các nhóm sử dụng Postman Enterprise, Postman cung cấp cho bạn quyền truy cập vào nhật ký thay đổi của các bộ sưu tập, không gian làm việc và API. Bạn có thể khôi phục các bộ sưu tập về thời điểm trước đó. Là nhà phát triển API trong nhóm, bạn sẽ cần điều này. Phần lớn là do Bob đã làm hỏng bộ sưu tập. Tuy nhiên, đôi khi bạn là Bob.

Quyền truy cập và tổ chức người dùng dựa trên vai trò

Không phải tất cả mọi người trong không gian làm việc của Postman đều có cùng mức quyền. Một số thành viên trong nhóm là người thử nghiệm và họ chỉ cần khả năng gửi yêu cầu và chạy thử nghiệm — nhưng không sửa đổi chúng. Những người khác có thể là nhà thiết kế chỉ được phép sửa đổi định nghĩa API.

Trong Postman, bạn có thể chỉ định vai trò cho các thành viên trong nhóm. Điều này ảnh hưởng đến loại quyền truy cập và mức độ quyền mà mỗi thành viên nhóm có trong một nhóm hoặc không gian làm việc.

Các nhóm cũng có thể có không gian làm việc riêng tư, hạn chế quyền truy cập của những người khác bên ngoài nhóm.

Tôi cũng nhận thấy rằng Postman Enterprise hỗ trợ “chụp tên miền”. Về cơ bản, điều này có nghĩa là bạn có thể thiết lập tất cả người dùng trong tổ chức của mình bằng cách cấp quyền truy cập cho mọi người từ miền mycompany.biz (ví dụ:).

Nhận xét và thảo luận nội tuyến

Postman có một tính năng cộng tác, có sẵn trên tất cả các gói của nó, không chỉ Enterprise Essentials. Đây là khả năng để các thành viên trong nhóm thêm nhận xét vào bộ sưu tập (trên thư mục, yêu cầu, ví dụ hoặc yêu cầu kéo). Có thể nhận xét và thảo luận trực tiếp trong Postman là điều rất quan trọng đối với việc phát triển API của nhóm. Vì hầu hết công việc phát triển API của nhóm bạn sẽ diễn ra trong Postman, nên bạn nên thảo luận ở đó (thay vì trong GitHub hoặc một số dịch vụ bên ngoài khác).

Phát triển API nhóm: Người đưa thư để giành chiến thắng

Bất cứ khi nào tôi tham gia một nhóm, tôi đều mang theo những công cụ mà tôi yêu thích nhưng tôi không thực sự áp đặt chúng lên đồng đội của mình. Tôi nghĩ họ có công cụ riêng. Vì vậy, đối với mỗi người của họ. Nhưng tôi có cảm giác rằng hầu hết các nhà phát triển API đều có Postman trong bộ công cụ của họ. Sẽ thật đáng tiếc nếu một số nhà phát triển API trong một nhóm đều sử dụng Postman riêng lẻ, với tư duy độc lập và không tận dụng được một số tính năng của nhóm này. Nếu họ tận dụng các tính năng của Postman Enterprise, họ sẽ nhận được…

Tăng hiệu quả

Trong không gian làm việc chung, bạn có thể bắt đầu với định nghĩa API được chia sẻ. Bất cứ khi nào một thành viên trong nhóm chỉnh sửa định nghĩa (hoặc tài liệu, bài kiểm tra hoặc môi trường), các chỉnh sửa sẽ được đồng bộ hóa và mọi người đều có bản mới nhất và tốt nhất.

Mọi người đều thực hiện cùng một nhóm yêu cầu trong một bộ sưu tập và mọi người đều có quyền truy cập vào tất cả các thử nghiệm sẽ được sử dụng. Tất cả những tiện ích này sẽ nâng cao hiệu quả của nhóm, từ đó sẽ đẩy tốc độ phát triển của họ tăng vọt.

Ít hiểu lầm hơn

Khi mọi người đang làm việc từ cùng một nguồn thông tin chính xác (không gian làm việc của bạn) và họ có thể đưa ra nhận xét cũng như trò chuyện trong công cụ họ đang sử dụng để phát triển, điều này sẽ dẫn đến ít hiểu lầm hơn. Nhóm của bạn sẽ không mất thời gian để nhầm lẫn về việc liệu điểm cuối đó có phải lấy thông số truy vấn hay thông số đường dẫn hay không. Mọi thứ sẽ rõ ràng.

Bài học chính

Tôi không biết rằng Postman dành cho các nhóm và doanh nghiệp. Bây giờ tôi đã biết, đây là bài học lớn của tôi: Các thành viên trong nhóm sử dụng những công cụ có lợi cho nhóm.

Người đưa thư thật tuyệt vời đối với tôi khi tôi là nhà phát triển API solo. May mắn thay, nó cũng có các tính năng giúp ích rất nhiều cho tôi khi tôi làm việc trong nhóm phát triển API. Đối với tôi, đó là sự đồng bộ hóa thời gian thực của các chỉnh sửa trong bộ sưu tập, nhật ký thay đổi và kiểm soát phiên bản cũng như các quyền chi tiết để truy cập. Bây giờ, tôi rất vui được đảm nhận các dự án API lớn hơn với các nhóm lớn hơn.

Chúc mừng mã hóa!

Cũng được xuất bản ở đây .