api-documentation（API 文档）

API Documentation Skill

Purpose

Define integration requirements and document API specifications to ensure smooth communication between systems (e.g., Frontend to Backend, or Service to Service).

When to Use

• Designing new API endpoints (e.g., FRS for Backend).
• Integrating with 3rd party services (e.g., Stripe, SendGrid).
• Documenting public APIs for partners.
• Defining payload structures for developers.

Key API Concepts for BAs

1. Protocols

• REST (Representational State Transfer): Most common. Resource-based.
• SOAP: Older, XML-based. Heavy enterprise use.
• GraphQL: Flexible, query-based. Client asks for exactly what it needs.

2. HTTP Methods (Verbs)

• GET: Retrieve data (Read).
• POST: Create new data (Create).
• PUT: Update/Replace full data (Update).
• PATCH: Update partial data (Update).
• DELETE: Remove data (Delete).

3. Status Codes

• 200 OK: Success.
• 201 Created: Success (new resource made).
• 400 Bad Request: Client error (invalid input).
• 401 Unauthorized: Authentication missing/failed.
• 403 Forbidden: Authentication passed, but permission denied.
• 404 Not Found: Resource doesn't exist.
• 500 Internal Server Error: Backend crashed.

Documentation Structure (Swagger/OpenAPI Style)

Required Sections per Endpoint

1. Title & Method: GET /api/v1/users/{userId}
2. Summary: One-line description of what it does.
3. Parameters:

- Path Params: Required ID in URL (e.g., {userId}). - Query Params: Filter/Sort limits (e.g., ?limit=10&role=admin). - Body: JSON payload (for POST/PUT). - Headers: Auth tokens, Content-Type.

1. Response Examples:

- Success (200) JSON body. - Error (4xx/5xx) JSON body.

1. Business Rules: Constraints, logic, side effects.

API Specification Template (Simple)

Endpoint: Create New Order

Method: POST URL: /api/v1/orders Description: Creates a new customer order and reserves inventory.

Request Headers:

• Authorization: Bearer <token>
• Content-Type: application/json

Request Body (JSON):

{
  "customerId": "uuid-string",
  "items": [
    {
      "productId": "uuid-string",
      "quantity": 2
    }
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Startown"
  }
}

Constraints:

• quantity must be > 0.
• customerId must be active.
• Max 20 items per order.

Success Response (201 Created):

{
  "orderId": "ord-12345",
  "status": "PENDING",
  "totalAmount": 150.00,
  "createdAt": "2026-01-21T10:00:00Z"
}

Error Responses:

• 400 Bad Request: "Invalid Quantity" or "Product Out of Stock".
• 401 Unauthorized: Token expired.

Mapping Integrations (Data Mapping)

When connecting System A to System B, create a Mapping Table:

Tools

• Swagger / OpenAPI: Standard for dev docs.
• Postman: Testing API calls.
• Stoplight: Visual API design.
• Lark Docs / Markdown: Writing specs for BRD/FRS.

Best Practices

• Be Consistent: Use ISO 8601 for dates (YYYY-MM-DDThh:mm:ssZ).
• Authentication: Explicitly state how auth works (API Key vs OAuth).
• Pagination: Don't return 1 million records. Specify default limits (limit=20).
• Error Messages: Define clear human-readable error messages.

Reference

• RESTful API Design Guide.
• OpenAPI Specification (OAS).