Việc soạn tài liệu API bằng Excel hoặc PDF rồi chia sẻ qua email là cách làm quá quen thuộc.
Khi có vấn đề phát sinh, chúng ta liên hệ người phụ trách, tìm lại email cũ để xác nhận phiên bản tài liệu mà phía khách hàng đang có. Sau đó lại giải thích những thay đổi, gửi tài liệu đã chỉnh sửa, rồi tiếp tục kiểm tra xem họ đã áp dụng đúng hay chưa.
Chúng ta lặp lại quy trình này quá nhiều đến mức bắt đầu xem đó là công việc vốn dĩ phải làm.
Nhưng vấn đề không dừng lại ở một tài liệu sai sót.
Mỗi khi API thay đổi, lại có thêm một tệp mới, một email mới, các ngoại lệ theo từng khách hàng và ký ức của người phụ trách chồng chất lên nhau. Ban đầu chỉ là chút bất tiện nhỏ, nhưng theo thời gian việc xác định tài liệu nào mới là chuẩn trở nên khó khăn hơn, đồng thời số người và thời gian cần để xử lý vấn đề cũng tăng lên.
Nếu khách hàng phát triển theo định dạng request của phiên bản cũ, sẽ phát sinh lỗi tích hợp và phải làm lại. Nếu các trường bắt buộc hoặc phương thức xác thực được truyền đạt khác đi, lịch trình phát triển sẽ bị chậm trễ; còn nếu đó là API đã vận hành rồi thì thậm chí có thể dẫn đến lỗi dữ liệu hoặc sự cố hệ thống.
Chỉ sau khi sự cố xảy ra, người ta mới phát hiện đội phát triển nội bộ và phía khách hàng đang nhìn vào hai tài liệu khác nhau.
Từ thời điểm đó, lập trình viên phải dừng công việc đang làm để xác minh nguyên nhân. Người phụ trách vận hành thì tìm lại tài liệu cũ và lịch sử đã gửi, còn phía khách hàng phải kiểm tra lại phần triển khai của mình cùng bản đặc tả đã nhận. Chỉ một chỗ lệch tài liệu cũng có thể khiến công việc của nhiều người cùng lúc bị đình lại.
Thế nhưng đa số vấn đề vẫn được âm thầm xử lý qua điện thoại, email và tin nhắn.
Có người gửi lại tệp đã sửa, có người giải thích tình hình cho khách hàng, còn lập trình viên thì vội vàng thêm xử lý ngoại lệ. Vấn đề trước mắt được giải quyết, nhưng vì sao nó xảy ra, khách hàng nào bị ảnh hưởng, và cần thay đổi điều gì để tránh lặp lại cùng một lỗi thì lại không được lưu lại trong tổ chức.
Thời gian dùng cho quá trình này lẽ ra phải được dành cho phát triển và cải tiến sản phẩm.
Vấn đề lớn hơn là toàn bộ quá trình này phụ thuộc vào kinh nghiệm, trí nhớ và hộp thư của một người phụ trách cụ thể. Khi người đó vắng mặt hoặc nghỉ việc, tổ chức phải lục lại email và lịch sử tin nhắn để khôi phục công việc từ đầu.
Tài liệu API không được quản lý sẽ không tự biến mất. Chúng tiếp tục tồn tại cả trong lẫn ngoài tổ chức và trở thành một khoản nợ tài liệu vô hình.
Có lẽ chúng ta không thật sự giải quyết vấn đề, mà chỉ đang quen với cách dùng thời gian của con người để chặn nó lại mỗi khi sự cố phát sinh.
Chính vì đã trải qua những vấn đề này trong công việc thực tế, tôi đã tạo ra SpecBridge.
SpecBridge không chỉ là công cụ để viết tài liệu API. Đây là công cụ vận hành tài liệu API, nơi có thể rà soát thay đổi và chỉ phân phối các phiên bản đã được phê duyệt cho khách hàng và đối tác bên ngoài.
Nó không thay thế Swagger hiện có, mà tập trung vào việc nhập Swagger/OpenAPI và Postman Collection rồi quản lý các vấn đề phát sinh trong quá trình chuyển giao ra bên ngoài.
- So sánh khác biệt giữa bản đang phát hành và bản đã chỉnh sửa
- Rà soát và phê duyệt thay đổi
- Tách biệt bản nháp và bản phát hành mà khách hàng nhìn thấy
- Quản lý phạm vi công khai tài liệu theo từng khách hàng
- Thiết lập mật khẩu và ngày hết hạn cho liên kết công khai
- Cung cấp tài liệu mới nhất đã được phê duyệt trên cùng một liên kết
Không cần gửi một tệp mới cho khách hàng mỗi lần nữa; chỉ cần phát hành lại trên liên kết cũ những tài liệu đã hoàn tất rà soát nội bộ.
Lập trình viên có thể giảm bớt công việc lặp đi lặp lại như tìm tài liệu và gửi lại, còn tổ chức thì có thể quản lý tài liệu API dựa trên lịch sử thay đổi đã được ghi nhận và tiêu chuẩn phát hành, thay vì dựa vào trí nhớ của một người phụ trách cụ thể.
Hiện tại tôi đang tìm các đối tác sẵn sàng sử dụng SpecBridge trong vận hành tài liệu API thực tế và đưa ra phản hồi thẳng thắn.
Nếu đội của bạn đang quản lý tài liệu API bằng Excel hoặc PDF, hoặc cứ mỗi lần API thay đổi lại phải gửi lại tài liệu cho khách hàng, tôi muốn cùng bạn kiểm chứng bắt đầu từ chính một tài liệu đang dùng hiện tại.
Tôi không mong những lời khen cho tính năng được làm tốt, mà muốn lắng nghe ý kiến chân thật về những điểm bất tiện trong vận hành thực tế, các quy trình không cần thiết và những tính năng còn thiếu.
Chưa có bình luận nào.