APIs 101: Introductions to APIs

HTTP Methods + Idempotency

Status Codes Cheat Sheet

Pagination & Filtering

For list endpoints, always support pagination and filters to keep responses fast and bills low.

• Offset/Limit: GET /users?offset=0&limit=50 (simple, but can skip items on fast-moving data)

• Cursor-based: GET /users?cursor=eyJpZCI6NDJ9&limit=50 (stable for real-time lists)

• Filtering: GET /users?role=admin&created_after=2025-01-01
  Return a total (optional), next_cursor, and honor limit caps. Document defaults.

Versioning & Deprecation Policy

Choose one: Path versioning (/v1/) or header versioning (Accept: application/vnd.example.v2+json). Keep versions stable for 12–18 months, publish a deprecation date, and surface warnings in responses:

Deprecation: true
Sunset: 2026-03-31
Link: <

This preserves trust and unlocks predictable migrations.

Request/Response Example (End-to-End)

Request

POST /v1/users
Content-Type: application/json
Authorization: Bearer <token>

{ "email": "lee@example.com", "role": "admin" }

Response

201 Created
Location: /v1/users/42

{ "id": 42, "email": "lee@example.com", "role": "admin", "created_at": "2025-10-06T10:00:00Z" }

Security Quick Checklist (Beginner Safe Defaults)

• Use HTTPS everywhere; reject plaintext (http) requests.

• Prefer OAuth 2.0/OIDC with short-lived tokens; rotate secrets.

• Scope tokens (least privilege) and validate audience/issuer.

• Enforce rate limits + 429 with Retry-After.

• Validate input (types, length, enums); never trust client data.

• Return generic errors; avoid leaking stack traces/IDs.

• Log with correlation IDs (no PII); alert on auth anomalies.

• CORS allow-lists; avoid * for credentials.

• Encrypt at rest; salt+hash passwords (if any).

• Review against OWASP API Top 10 quarterly.

REST vs GraphQL vs gRPC (When to pick what)

• REST: Simple, cache-friendly, great for CRUD and public APIs.

• GraphQL: Flexible queries; fewer round-trips; needs schema governance.

• gRPC: Binary, fast, contract-first; ideal for internal microservices.
  Choose: Public/third-party → REST; complex client data needs → GraphQL; high-throughput service-to-service → gRPC.

Common Pitfalls & Quick Fixes

• Breaking changes: Add fields instead of changing types; deprecate with headers first.

• Non-idempotent retries: Use idempotency keys for POST (e.g., Idempotency-Key header).

• Unbounded lists: Add pagination and caps; reject limit>1000.

• Leaky errors: Map internal errors to clean 4xx/5xx + support code.

Streamlining API Process

APIs streamline processes and help reduce errors. For instance, e-commerce APIs ensure inventory stays in sync across all sales channels, preventing overselling. In healthcare, APIs can automatically update provider calendars when patients book appointments.

APIs also play a key role in connecting platforms across industries. In financial services, where real-time data accuracy is critical, APIs automate tasks like transaction verification and updating account balances across banking systems.

Here are some tips for working with APIs effectively:

• Store API keys securely: Use environment variables to keep your keys safe.

• Double-check data accuracy: Compare results from multiple trusted sources to ensure reliability.

For communication, REST is ideal for standard request-response exchanges, while WebSocket is better suited for continuous real-time updates. To save development time, you can integrate pre-built services like Google Maps for location data or Facebook Login for authentication.

Beginner Testing Workflow

Start with contract tests (does each endpoint honor schema, codes, and auth?), then happy-path flows (signup → login → create → read), and finally negative tests (invalid body, missing token, rate-limit). Automate these in CI/CD and run on every merge; gate releases on critical flows. For teams, use environments and secrets management to keep credentials out of code.