Skip to content
Skills Library
Programming · Tool integration

tech-api-integration

/tech-api-integration

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

Repository
skills ↗
Licence
MIT
Last repository change
06.06.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 06.06.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Triggers from the description

connect to this APIwhy is the API returning errorshow do I authenticatebuild an API integration
Original author description

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

How it works

  1. Framework
  2. Output Format
  3. Gotchas
  4. References
Original SKILL.md headings · 128 lines, 757 words
SKILL.md preview
---
name: "tech-api-integration"
description: "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'."
metadata:
  category: "WP-11 通用技術"
  tags: ["technology", "api", "rest", "integration"]
---

# REST API Integration Guide

## Framework

```
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

1. [ ] Read API documentation completely
2. [ ] Test auth flow (get valid token/key)
3. [ ] Test each endpoint with curl/Postman first
4. [ ] Implement error handling for all status code ranges
5. [ ] Implement rate limit handling
6. [ ] Implement retry logic with backoff
7. [ ] Log all requests and responses (redact secrets)
8. [ ] Handle API versioning (pin to specific version)
9. [ ] Set timeouts (connect: 5s, read: 30s)
10. [ ] Monitor for API deprecation notices

## Output Format

```markdown
# API Integration Plan: {API Name}

## API 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`
Files in this package (4)
  • SKILL.md 5 KB
  • examples/sample_scenario.md 6 KB
  • references/oauth-guide.md 15 KB
  • references/webhook-patterns.md 14 KB

Versions

The database has no other skills named tech-api-integration.

Database snapshot: 13.11.2026 · package version 3e30dc22174a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-design
    REST API design patterns for resource naming, HTTP methods, status codes, pagination strategy, error envelopes, versioning, and rate limiting. Use when designing, reviewing, or refactoring HTTP APIs and endpoint contracts.
  • 100bc-api-rest
    Use BigCommerce REST APIs — V2 and V3 endpoints, authentication, rate limiting, pagination, filtering, batch operations, and error handling. Use when integrating with BigCommerce data via REST API.
  • 90agent-api-integration-specialist
    Specialist subagent: Third-party API integration, webhook handling, OAuth flows, rate limiting, and SDK wrapping specialist. Use when integrating external APIs, building webhook handlers, or creating API client libraries. Trigger phrases: API integration, webhook, third-party…
  • 100rest-api-best-practices
    REST API design guidance. Use when designing or reviewing REST endpoints, choosing HTTP methods and status codes, defining URL structure and naming conventions, formatting error responses, implementing pagination or filtering, versioning an API, securing endpoints with…
  • 100api-design
    REST API conventions covering URL structure, HTTP methods, status codes, pagination, filtering, error responses, and versioning. Use when designing or reviewing REST API endpoints, adding routes, or standardizing API error handling.
  • 100api-integration
    Integrate external REST APIs with proper authentication, rate limiting, error handling, and caching patterns. Use when working with external APIs, building API clients, or fetching data from third-party services.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.