Làm cách nào để ghi lại các yêu cầu cho một API một cách có hệ thống?

Tôi hiện đang làm việc trong một dự án, nơi tôi phải phân tích các yêu cầu của hai hệ thống CNTT nhất định, sử dụng điện toán đám mây, cho API đám mây. Nói cách khác, tôi phải phân tích những yêu cầu nào mà các hệ thống này có đối với API đám mây, sao cho chúng có thể chuyển đổi nó, trong khi có thể hoàn thành các mục tiêu hiện tại của mình.

Để tôi cho bạn một ví dụ cho một số yêu cầu không chính thức của Dự án A:

1. Khi khởi động các máy ảo trong đám mây thông qua API, phải có thể chỉ định kích thước bộ nhớ, loại CPU, hệ điều hành và khóa SSH cho người dùng root.
2. Có thể giám sát lưu lượng mạng trong và ngoài nước mỗi giờ trên mỗi máy ảo.
3. API phải hỗ trợ việc gán IP công cộng cho máy ảo và truy xuất IP công cộng.
4. ...

Trong giai đoạn sau của dự án, tôi sẽ phân tích một số tiêu chuẩn Điện toán đám mây tiêu chuẩn hóa API đám mây để tìm ra những thiếu sót có thể có trong các tiêu chuẩn hiện tại. Một phát hiện có thể và có thể sẽ là, một tiêu chuẩn nhất định không hỗ trợ giám sát việc sử dụng tài nguyên và do đó hiện không thể sử dụng được.

Tôi hiện đang cố gắng tìm cách viết ra một cách có hệ thống và phân loại các yêu cầu của tôi. Tôi cảm thấy rằng cách tôi hiện đang viết chúng ra (như ba điểm trên) là quá không chính thức.

Tôi đã đọc trong một vài yêu cầu về sách và kiến ​​trúc phần mềm, nhưng tất cả chúng đều tập trung quá nhiều vào chi tiết và cách thực hiện. Tôi thực sự chỉ quan tâm đến các chức năng được cung cấp thông qua API / giao diện và tôi không nghĩ các sơ đồ UML, v.v. là lựa chọn phù hợp với tôi. Tôi nghĩ hiện tại các yêu cầu mà tôi thu thập có thể được mô tả là câu chuyện của người dùng, nhưng điều đó đã đủ cho một phân tích yêu cầu phức tạp chưa? Có lẽ tôi nên đi "sâu hơn một cấp" ...

Đọc Tài liệu kiến ​​trúc phần mềm, ấn bản thứ hai: Lượt xem và xa hơn , Chương 7: Giao diện phần mềm tài liệu.

Hoặc ít nhất là kiểm tra một số tài liệu API nổi tiếng, như của Google ( Bản đồ , GData - lỗi thời nhưng phức tạp) của Amazon ( S3 ) hoặc kiểm tra tài liệu cho các ứng dụng và dịch vụ của Microsoft, được tập hợp lại trên MSDN (cho các dịch vụ Trực tiếp , nhưng ngay cả đối với Windows )

Thông thường một tài liệu API có 3 phần:

• một cái nhìn tổng quan về những gì nó được làm, những gì ai đó có thể làm từ nó, có lẽ là một tổng quan kiến ​​trúc
• Hướng dẫn của nhà phát triển, giải thích một số tác vụ phổ biến với API, thường là với các mẫu mã và các ứng dụng mẫu có thể tải xuống.
• Tham chiếu API về cách thức hoạt động của nó

Về lý thuyết - nếu chúng tôi tin rằng Tháng huyền thoại của Brook - bạn thiết kế tài liệu và đảm bảo có một triển khai phù hợp.

Bây giờ trở lại để thực hành

Yêu cầu thiết kế cho một API giống như bất kỳ thiết kế phần mềm nào.

1. Bạn tranh thủ sự khác nhau diễn viên người sẽ được sử dụng API (sử dụng một sơ đồ bối cảnh ví dụ)
2. Bạn nêu chi tiết nhu cầu tiêu biểu của từng diễn viên trong hệ thống với các trường hợp sử dụng
3. Đối với mỗi trường hợp sử dụng, bạn phát triển một tập hợp các kịch bản về cách sử dụng hệ thống tưởng tượng (cuốn sách Viết các trường hợp sử dụng hiệu quả có thể giúp bạn về điều đó)
4. Bạn có thể tạo sơ đồ mạnh mẽ , sơ đồ trình tự hoặc sơ đồ hoạt động , nhưng bạn thiết kế hành vi dựa trên các kịch bản để tìm ra thông điệp nào cần thiết để được thông qua
5. Từ các tin nhắn, bạn suy ra kiến trúc dữ liệu cơ bản , bằng cách xem xét các tham số cần thiết cho mỗi thông báo để được truyền đạt thành công.

Nhiều người sẽ bắt đầu với cấu trúc dữ liệu cơ bản, nhưng tôi nghĩ điều đó thật ngớ ngẩn: máy tính (và các đối tượng, cho vấn đề đó) là về sự tương tác. Bạn cần hiểu những gì cần được truyền đạt từ hai phía để có thể tương tác thành công. Dữ liệu chỉ là tham số của các tương tác đó.

Tôi thường làm sơ đồ hoạt động hoặc sơ đồ đơn giản hiển thị các đối số được truyền dưới dạng đối tượng hoặc lớp. Đó là, có một luồng kiểm soát đang diễn ra, nhưng chúng ta thấy thông tin nào mà một trong các bên đã chuyển cho bên kia.

Sau khi hoàn thành tất cả những điều này, bạn lấy lại kịch bản của mình và bắt đầu thực hiện các bài kiểm tra chấp nhận . Đó là bởi vì các API máy tính sẽ được sử dụng bởi các máy khách, do đó, mã đầu tiên của bạn phải là máy khách máy tính tự động truy xuất dưới dạng thử nghiệm.

Các thử nghiệm chấp nhận được viết dưới dạng "đầu vào được cung cấp" - "đầu ra dự kiến" hoặc dưới dạng mã. Bạn có thể tìm thấy rất nhiều sách về BDD và TDD sẽ giải thích cho bạn cách viết bài kiểm tra tốt.

Ngoài ra, xung quanh đây, bạn bắt đầu đưa ra các cuốn sách về giao diện REST và tương tự trong trường hợp bạn đang xây dựng API web, vì các thử nghiệm của bạn phải được thực thi từ ngày đầu tiên.

Từ các kịch bản, bạn cũng xây dựng mã mẫu và hướng dẫn của nhà phát triển.

Từ sơ đồ trình tự và sơ đồ kiến ​​trúc dữ liệu, bạn phát triển tham chiếu API.

Thêm một rắc HTML, đảm bảo tất cả các bài kiểm tra đều vượt qua và ứng dụng của bạn đủ nhanh, an toàn và đủ mạnh, và hãy cùng giải quyết nó!

(Tôi biết, đây là thác nước-ish: Agile là như nhau, ngoại trừ bạn luôn chỉ làm một phần nhỏ trong số này, ví dụ: một vài kịch bản cho mỗi lần chạy nước rút)

Bạn thực sự không cần phải nhận được bất kỳ "chính thức" hơn những gì bạn có. Bạn đang viết nó cho con người đọc và có lẽ chủ yếu là chính bạn, vì vậy hãy ghi nhớ điều đó. Một đề nghị của tôi là đặt nó trong một hệ thống phân cấp và đánh số nó ở định dạng phác thảo. Bằng cách đó trong các bài đánh giá, danh sách kiểm tra, v.v., bạn có thể tham khảo một số như 3.0.1 như một cách viết tắt và để dễ dàng phân biệt những gì bạn đang nói.