API Design Documentation

Skill Name: sa-api-design

Background & Applicable Scenarios

The architecture design tells you what modules exist, but you also need to clarify how modules communicate with each other, what interfaces are exposed externally, and what the specifications are for calling external system interfaces. This skill refines architecture-level interface design down to the API level, providing a unified protocol for frontend, backend, and external system integration.

Input & Output

What you need to provide: Interface architecture section from the Architecture Design Specification + Requirements Specification + Data Dictionary (including data flow diagrams, ER diagrams) + External system inventory and interface documentation.

What you will get: System boundary interface design document, including: externally exposed interface definitions (request/response formats, error codes), external call interface specifications, internal key interface definitions supporting the above interfaces, and unified interface protocol specifications.

Process Description

The Agent first searches the interface design knowledge base, then confirms the boundary interface scope with you. Next, it designs in three steps: which interfaces are exposed externally, how to integrate with external system calls, and how internal key interfaces supporting the above are defined. Each step is confirmed before moving to the next, ultimately producing a unified interface protocol specification document.

flowchart TD s0["Interface Design KB Retrieval: Load integration patterns, interface specifications, lessons learned from engineering KB"] s1["Boundary Interface Scope Confirmation: Extract defined interfaces from Architecture §6, confirm design scope"] s2["Boundary Interface Scope Inquiry Round"] s3["External Interface Detailed Design: Request/response definitions, business rules, interaction flows"] s4["External Call Interface Integration Design: Call info, request construction, response handling, reliability assurance"] s5["Internal Key Interface Definitions: Identify key internal calls, define at interface level"] s6["Document Integration & Full Review"] s0 --> s1 s1 --> s2 s2 --> s3 s3 --> s4 s4 --> s5 s5 --> s6