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

•Title & Method: GET /api/v1/users/{userId}
•Summary: One-line description of what it does.
•
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.
•
Response Examples:
- •Success (200) JSON body.
- •Error (4xx/5xx) JSON body.
•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):

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):

json

{
  "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:

Source Field (System A)	Type	Transformation	Destination Field (System B)	Type	Notes
`first_name`	Str	Concat	`FullName`	Str	A.first + " " + A.last
`last_name`	Str	(above)	-	-
`dob`	Date	Format `YYYY-MM-DD`	`BirthDate`	Str	B requires string format
`status`	Enum	Map 'Active'->1	`IsActive`	Bool	Logic mapping

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).