API là gì? Giới thiệu API cơ bản và ứng dụng trong DevOps

Bài viết này là phần trong series về Cache là gì và User vs Request — các khái niệm nền tảng trong DevOps. Nếu bạn quan tâm đến CI/CD, xem thêm bài Docker là gì để hiểu cách container hóa ứng dụng phục vụ deploy.

API là gì — hiểu đơn giản

Khi bạn vào nhà hàng, bạn không vào bếp lấy đồ ăn. Bạn gọi món qua người phục vụ. Người phục vụ đó là API — trung gian giữa bạn (client) và nhà bếp (server).

Trong lập trình, API là tập hợp quy tắc cho phép một ứng dụng yêu cầu dữ liệu hoặc thực hiện hành động từ ứng dụng khác, mà không cần biết bên trong nó hoạt động thế nào.

API không phải là một thứ duy nhất

“API” là khái niệm chung. Có nhiều loại API:

• REST API — phổ biến nhất, dùng HTTP
• GraphQL — query linh hoạt hơn REST
• gRPC — của Google, nhanh, dùng Protocol Buffers
• WebSocket — kết nối hai chiều, real-time
• CLI API — lệnh terminal cũng là một dạng API

Bài này tập trung vào REST API vì nó được dùng phổ biến nhất trong DevOps.

HTTP — nền tảng của REST API

REST API chạy trên HTTP. Muốn hiểu API, trước tiên hiểu HTTP.

HTTP Methods

Mỗi HTTP request có một method (phương thức) cho biết hành động muốn thực hiện:

Method	Ý nghĩa	Ví dụ
GET	Lấy dữ liệu	GET /users — lấy danh sách users
POST	Tạo mới	POST /users — tạo user mới
PUT	Thay thế toàn bộ	PUT /users/1 — thay thế user ID 1
PATCH	Cập nhật một phần	PATCH /users/1 — sửa email user 1
DELETE	Xóa	DELETE /users/1 — xóa user 1

HTTP Status Codes

Server trả về status code cho biết kết quả:

Code	Loại	Ý nghĩa
2xx	Success	200 OK, 201 Created, 204 No Content
3xx	Redirect	301 Moved, 304 Not Modified
4xx	Client Error	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
5xx	Server Error	500 Internal Error, 502 Bad Gateway, 503 Service Unavailable

Request và Response

Một HTTP request gồm:

• Method — GET, POST, PUT…
• URL — endpoint (VD: api.example.com/users/123)
• Headers — metadata (Content-Type, Authorization…)
• Body — dữ liệu gửi kèm (thường dùng với POST/PUT)

Response gồm:

• Status Code — 200, 404, 500…
• Headers — metadata response
• Body — dữ liệu trả về

JSON — định dạng dữ liệu phổ biến nhất

API thường trả dữ liệu dạng JSON (JavaScript Object Notation). Nó nhẹ, dễ đọc, và hầu hết ngôn ngữ đều hỗ trợ.

# Ví dụ JSON response
{
    "id": 1,
    "name": "Nguyen Van A",
    "email": "a@example.com",
    "role": "admin",
    "created_at": "2024-01-15T10:30:00Z"
}

# Array JSON
{
    "users": [
        {"id": 1, "name": "A"},
        {"id": 2, "name": "B"}
    ],
    "total": 2,
    "page": 1
}

Authentication — API Key vs Token

API cần biết “ai đang gọi”. Có vài cách phổ biến:

1. API Key

Key đơn giản, gửi kèm mỗi request:

curl -H "X-API-Key: your-secret-key" https://api.example.com/data

# Hoặc trong header Authorization
curl -H "Authorization: Bearer your-api-key" https://api.example.com/data

Dùng cho: internal API, service-to-service communication.

2. JWT Token

Token có thời hạn, chứa thông tin user:

# 1. Login để lấy token
curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "secret"}'

# Response:
# {"token": "eyJhbGciOiJIUzI1NiIs..."}

# 2. Dùng token để gọi API
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.example.com/protected

Thực hành: Gọi API bằng curl

curl là công cụ dòng lệnh phổ biến để test API. Cài sẵn trên Linux/macOS.

GET — Lấy dữ liệu

# GET request đơn giản
curl https://api.example.com/users

# GET với query params
curl "https://api.example.com/users?page=2&limit=10"

# GET với headers
curl -H "Accept: application/json" \
     -H "Authorization: Bearer token123" \
     https://api.example.com/users/1

POST — Tạo mới

# POST với JSON body
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token123" \
  -d '{
    "name": "Tran Van B",
    "email": "b@example.com",
    "role": "user"
  }'

# Response: 201 Created
# {"id": 5, "name": "Tran Van B", ...}

PUT/PATCH — Cập nhật

# PUT - thay thế toàn bộ
curl -X PUT https://api.example.com/users/5 \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "email": "new@example.com", "role": "admin"}'

# PATCH - cập nhật một phần
curl -X PATCH https://api.example.com/users/5 \
  -H "Content-Type: application/json" \
  -d '{"email": "new@example.com"}'

DELETE — Xóa

curl -X DELETE https://api.example.com/users/5 \
  -H "Authorization: Bearer token123"

# Response: 204 No Content (thành công, không trả gì)

API trong DevOps — Ứng dụng thực tế

API là xương sống của DevOps. Gần như mọi công cụ DevOps đều có API.

1. CI/CD Pipeline — Gọi API tự động

GitHub Actions, GitLab CI, Jenkins đều có API để trigger pipeline, lấy log, deploy:

# Trigger GitHub Actions workflow
curl -X POST \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/owner/repo/actions/workflows/main.yml/dispatches \
  -d '{"ref": "main"}'

# Trigger Jenkins job
curl -X POST "http://jenkins:8080/job/my-job/build" \
  --user "admin:api-token" \
  --data "token=secret-token"

2. Docker Registry — Push/Pull Image

# Docker Hub API - lấy thông tin image
curl -H "Authorization: Bearer YOUR_DOCKER_TOKEN" \
  https://hub.docker.com/v2/repositories/library/nginx/

# Response:
# {"name": "nginx", "description": "...", "star_count": 1200, ...}

3. Cloud Provider — Infrastructure as Code

AWS, GCP, Azure đều có API để tạo/sửa/xóa tài nguyên:

# AWS CLI cũng gọi API bên dưới
aws ec2 describe-instances

# Tương đương API trực tiếp (AWS Signature)
curl -X POST "https://ec2.amazonaws.com/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "Action=DescribeInstances&Version=2016-11-15"

# Terraform gọi API để tạo infrastructure
# terraform plan/apply thực chất là gọi cloud provider API

# Kubernetes API - lấy pods
curl -k -H "Authorization: Bearer $TOKEN" \
  https://kubernetes.api:6443/api/v1/namespaces/default/pods

4. Monitoring — Lấy metrics và alert

# Prometheus API - query metrics
curl "http://prometheus:9090/api/v1/query?query=up"

# Prometheus Alertmanager - gửi alert
curl -X POST "http://alertmanager:9093/api/v1/alerts" \
  -H "Content-Type: application/json" \
  -d '[{"labels": {"alertname": "HighCPU"}, "annotations": {"summary": "CPU cao"}}]'

# Grafana API - tạo dashboard
curl -X POST "http://grafana:3000/api/dashboards/db" \
  -H "Authorization: Bearer $GRAFANA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboard": {
      "title": "My Dashboard",
      "panels": [...]
    }
  }'

5. Notification — Gửi Slack, Email, SMS

# Slack Incoming Webhook
curl -X POST "https://hooks.slack.com/services/xxx/yyy/zzz" \
  -H "Content-Type: application/json" \
  -d '{"text": "Deploy thành công! :white_check_mark:"}'

# Discord webhook
curl -X POST "https://discord.com/api/webhooks/xxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "Server đang online"}'

6. Secrets Management — HashiCorp Vault

# Vault API - đọc secret
curl -H "X-Vault-Token: $VAULT_TOKEN" \
  "http://vault:8200/v1/secret/data/database"

# Response:
# {"data": {"data": {"password": "db-secret-password"}}}

# Tạo secret mới
curl -X POST "http://vault:8200/v1/secret/data/api-key" \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"data": {"key": "abc123"}}}'

7. Database — Backup tự động

# MongoDB Atlas API - tạo backup
curl -X POST \
  "https://cloud.mongodb.com/api/atlas/v1.0/groups/$GROUP_ID/clusters/$CLUSTER_ID/backup/snapshots" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json"

Script tự động hóa với Python

Ngoài curl, Python là ngôn ngữ phổ biến để làm việc với API trong DevOps:

# Gọi API với Python (requests library)
import requests

# GET request
response = requests.get(
    "https://api.github.com/repos/owner/repo",
    headers={"Authorization": "token YOUR_TOKEN"}
)
print(response.status_code)
print(response.json())

# POST request
data = {"name": "new-repo", "private": True}
response = requests.post(
    "https://api.github.com/user/repos",
    headers={"Authorization": "token YOUR_TOKEN"},
    json=data
)
print(response.status_code, response.json())

# Ví dụ: Auto-deploy khi có commit mới
import requests

GITHUB_API = "https://api.github.com"
TOKEN = "your-github-token"
DEPLOY_SERVER = "https://deploy.example.com"

def check_new_commits():
    # Lấy commit mới nhất
    response = requests.get(
        f"{GITHUB_API}/repos/owner/repo/commits",
        headers={"Authorization": f"token {TOKEN}"}
    )
    commits = response.json()
    latest = commits[0]['sha']
    
    # Trigger deploy
    requests.post(
        DEPLOY_SERVER,
        json={"commit_sha": latest, "branch": "main"}
    )
    print(f"Deploying commit: {latest[:7]}")

Best practices khi làm việc với API

• Dùng HTTPS luôn — không gửi credentials qua HTTP thường
• Retry logic — API có thể fail tạm thời, thêm retry với exponential backoff
• Timeout — đặt timeout để tránh request treo vĩnh viễn
• Rate limiting — nhiều API giới hạn số request/phút, kiểm tra và chờ khi bị limit
• Logging — log request và response để debug
• Secret management — không hardcode API key trong code, dùng env vars hoặc Vault

# Ví dụ: Retry với exponential backoff
import time
import requests

def call_api_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, timeout=10)
            response.raise_for_status()
            return response.json()
        except (requests.exceptions.Timeout, 
                requests.exceptions.ConnectionError) as e:
            wait = 2 ** attempt  # 1s, 2s, 4s
            print(f"Retry {attempt + 1}/{max_retries} sau {wait}s")
            time.sleep(wait)
    raise Exception(f"Failed sau {max_retries} attempts")

Công cụ hỗ trợ làm việc với API

• Postman — GUI để test API, lưu collection
• Insomnia — alternative cho Postman, nhẹ hơn
• HTTPie — curl nhưng dễ đọc hơn (http GET example.com/api)
• Bruno — mã nguồn mở, lưu API tests trong Git
• curl — có sẵn, dùng cho script tự động

Tham khảo

Tài liệu chính thức về HTTP methods và status codes: MDN HTTP Methods. Tìm hiểu thêm về REST API design tại RESTfulAPI.net. Với DevOps, HashiCorp Vault Documentation và Docker Engine API là tài liệu tham khảo hữu ích.

Kết luận

API là cách mọi thứ trong DevOps kết nối với nhau. Từ việc trigger một CI/CD pipeline đến gửi notification khi deploy xong, tất cả đều đi qua API. Nắm vững HTTP methods, status codes, JSON và cách gọi API bằng curl hoặc Python là kỹ năng nền tảng mà bất kỳ DevOps engineer nào cũng cần.

Bước tiếp theo: thực hành với một API thật — có thể là GitHub API, một cloud provider, hoặc dịch vụ bạn đang dùng. Đọc documentation, thử các endpoint, và viết script tự động hóa cho công việc hàng ngày.

API (Application Programming Interface) là cách để phần mềm nói chuyện với nhau. Trong DevOps, API xuất hiện ở khắp nơi — từ CI/CD pipeline đến monitoring, từ cloud infrastructure đến notification. Nắm vững API không chỉ là kỹ năng của developer, mà là yêu cầu cơ bản của bất kỳ ai làm DevOps.