REST API Integration Guide REST API 整合指南

Released已發布

methodology methodology

Guide REST API integration including HTTP methods, authentication, error handling, and rate limiting. Use this skill when the user needs to connect to a third-party API, design an API client, troubleshoot API errors, or understand API concepts — even if they say 'connect to this API', 'why is the API returning errors', 'how do I authenticate', or 'build an API integration'.

技術方法論技能：REST API Integration Guide 分析與應用。

Methodology方法論

IRON LAW: Read the Docs, Then Build, Then Handle Errors

1. Read the API documentation completely (auth, endpoints, rate limits, errors)
2. Get a successful request working in isolation (curl/Postman)
3. Build error handling BEFORE building features

Skipping step 1 wastes hours on trial-and-error. Skipping step 3
creates fragile integrations that break silently in production.

HTTP Methods

Method	Purpose	Idempotent?	Example
GET	Read data	Yes	`GET /users/123`
POST	Create new resource	No	`POST /users` + body
PUT	Replace entire resource	Yes	`PUT /users/123` + full body
PATCH	Update partial resource	Yes	`PATCH /users/123` + partial body
DELETE	Remove resource	Yes	`DELETE /users/123`

Status Codes

Range	Meaning	Common Codes
2xx	Success	200 OK, 201 Created, 204 No Content
3xx	Redirect	301 Moved, 304 Not Modified
4xx	Client error (your fault)	400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests
5xx	Server error (their fault)	500 Internal, 502 Bad Gateway, 503 Service Unavailable

Authentication Types

Type	How It Works	When Used
API Key	Key in header or query param	Simple APIs, server-to-server
Bearer Token	`Authorization: Bearer <token>`	OAuth 2.0, JWT-based APIs
OAuth 2.0	Token exchange flow (authorize → token → API call)	User-delegated access (Google, FB)
Basic Auth	Base64(username:password) in header	Legacy, internal APIs
HMAC Signature	Sign request with secret key	Payment gateways, high-security

Error Handling Strategy

try:
    response = api.call(request)
    if response.status == 429:  # Rate limited
        wait(response.headers['Retry-After'])
        retry()
    elif response.status >= 500:  # Server error
        retry_with_backoff(max_retries=3)
    elif response.status >= 400:  # Client error
        log_error(response.body)
        raise ClientError(response.body['message'])
    else:
        return response.json()

Rate Limiting

Strategy	How
Respect `Retry-After` header	Wait the specified seconds before retrying
Exponential backoff	Wait 1s, 2s, 4s, 8s between retries
Token bucket	Track request count, pause when approaching limit
Queue requests	Use a job queue (Celery, Bull) for high-volume integrations

Integration Checklist

Output Format輸出格式

# API Integration Plan: {API Name}

Overview概述

Base URL: {url}
Auth: {type}
Rate limit: {N requests/period}
Documentation: {link}

Endpoints Used

Endpoint	Method	Purpose	Auth
{path}	GET/POST	{what it does}	{auth type}

Error Handling

Error	Response	Our Action
401	Unauthorized	Refresh token, retry
429	Rate limited	Backoff, retry after Retry-After
500	Server error	Retry 3x with exponential backoff

Implementation Timeline

Phase	Task	Duration
1	Auth + basic call	{days}
2	Full integration	{days}
3	Error handling + monitoring	{days}

Gotchas注意事項

Sandbox vs production: Most APIs have a sandbox/test environment. Build and test there first. Production API keys should never be in code.
Pagination: APIs return paginated results. Handle all pages, not just the first. Check for next_page token or offset parameter.
Webhook reliability: If using webhooks, implement idempotent handlers (same event received twice should not duplicate data). Store event IDs to deduplicate.
API changes break things: Pin to a specific API version. Subscribe to the provider's changelog/deprecation notices.
Secrets management: API keys and tokens NEVER in source code. Use environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault).

References參考資料

For OAuth 2.0 flow details, see references/oauth-guide.md
For webhook implementation patterns, see references/webhook-patterns.md

Tags標籤

technologyapirestintegration