Quick Reference
API Design
API Selection
Protocol Choice
- REST : Default for most designs; standard HTTP CRUD over resource URLs.
- GraphQL : Use for diverse clients and over-fetching or under-fetching; adds complexity.
- RPC : Use for internal microservices or performance-critical calls; action-oriented.
- WebSockets or Server-Sent Events: Use for notifications, chat, or live updates; persistent connections.
GraphQL Design
- Schema relationships : Define entity links directly so clients traverse them in one query.
- N+1 problem : Parent query plus N child queries; fix with batching or dataloader patterns.
- Field-level authorization : Secure individual fields in resolvers, not just entire endpoints.
REST Basics
Resource Shape
- Resource nouns : Model things, not actions; use plural nouns like events or bookings.
- Parent-child nesting : Use clear ownership like /events/{id}/tickets when a child belongs under a parent.
Method Semantics
- GET : Retrieve without changing state; idempotent.
- POST : Create resources; not safe or idempotent, so retries can duplicate bookings.
- PUT : Replace a full resource or create it if absent; idempotent.
- PATCH : Update part of a resource; idempotency depends on the operation.
- DELETE : Remove a resource; idempotent even if later responses differ.
Input Placement
- Path parameters : Required identifiers for a specific resource, e.g., /events/123.
- Query parameters : Optional filters, sorting, behavior, or pagination, e.g., ?city=NYC&limit=20.
- Request body : Complex create or update payloads; use for data too large or sensitive for URLs.
Response Codes
- 200 Success : Request succeeded; response body is typically JSON.
- 201 Created : Resource created; return the newly created resource.
- 4xx Client Errors : 400 bad request, 401 auth required, 404 not found.
- 5xx Server Errors : 500 for server errors; distinguish these from client errors.
Shared Patterns
Pagination Choice
- Offset-based Pagination : Default for most interviews; simple offset/limit but shifts can duplicate or miss records.
- Cursor-based Pagination : Stable under new records by using a pointer; harder to jump to page 5.
Versioning Choice
- URL Versioning : Default for interviews; explicit paths like /v1/events or /v2/events.
- Header Versioning : Cleaner URLs, but less obvious and harder to test in browsers.
Security
Credential Choice
- JWT Tokens : Default for user-facing sessions; carry user ID, permissions, and expiration.
- API Keys : Use for internal services or third-party developers, not human user sessions.
Authorization Model
- RBAC : Assign permissions to roles.
- Role examples : Roles like customer, venue_manager, and admin.
Abuse Prevention
- Rate Limiting : Limit API use.
- Limit scopes and thresholds : Limit per user/IP/endpoint, e.g., 1000/hour, 100/hour, 10 booking attempts/min; return 429.