API Documentation — Cách Đọc và Viết cho Developer

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

## Create a new order

Creates a new order for the specified user.

**Endpoint:** `POST /api/v2/users/{userId}/orders`

### Path Parameters

| Parameter | Type   | Required | Description          |
|-----------|--------|----------|----------------------|
| userId    | string | Yes      | The unique user ID   |

### Request Headers

| Header        | Value              | Required | Description        |
|---------------|--------------------|----------|--------------------|
| Authorization | Bearer {token}     | Yes      | API authentication |
| Content-Type  | application/json   | Yes      | Request body format|

### Request Body

| Field     | Type    | Required | Description                    |
|-----------|---------|----------|--------------------------------|
| productId | string  | Yes      | ID of the product to order     |
| quantity  | integer | Yes      | Number of items (min: 1)       |
| notes     | string  | No       | Optional order notes           |
| coupon    | string  | No       | Discount coupon code           |

### Example Request

    curl -X POST https://api.example.com/api/v2/users/usr_123/orders \
      -H "Authorization: Bearer sk_live_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "productId": "prod_456",
        "quantity": 2,
        "notes": "Gift wrap please"
      }'

### Response

**Status: 201 Created**

    {
      "id": "ord_789",
      "userId": "usr_123",
      "productId": "prod_456",
      "quantity": 2,
      "status": "pending",
      "createdAt": "2026-03-14T10:30:00Z"
    }

### Error Responses

| Status | Code              | Description               |
|--------|-------------------|---------------------------|
| 400    | invalid_request   | Missing required fields   |
| 401    | unauthorized      | Invalid or expired token  |
| 404    | user_not_found    | User ID does not exist    |
| 429    | rate_limit        | Too many requests         |

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# OpenAPI 3.0 Specification
openapi: 3.0.3
info:
  title: User Management API
  description: API for managing users and their profiles.
  version: 2.1.0

paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      description: |
        Returns a single user object. Requires authentication.
        **Note:** This endpoint is rate-limited to 100 req/min.
      parameters:
        - name: userId
          in: path
          required: true
          description: Unique identifier of the user
          schema:
            type: string
            example: "usr_abc123"
      responses:
        '200':
          description: User found successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          description: Unique user ID
        email:
          type: string
          format: email
          description: User's email address
        name:
          type: string
          nullable: true
          description: Display name (optional)
        role:
          type: string
          enum: [admin, editor, viewer]
          description: User's role in the system
        createdAt:
          type: string
          format: date-time