How to Design APIs Like a Senior Engineer (REST, GraphQL, Auth, Security)

API Design Course Overview (what the video covers)

• Positions API design as more than CRUD: in production, APIs strongly influence performance, security, scalability, and how other teams integrate.
• Promises a “complete picture” of how APIs work end-to-end: design → development → deployment → maintenance → deprecation.
• Core topics: REST, GraphQL, gRPC, plus authentication/authorization, and API security against attacks.
• Mentions a follow-up lesson focus: deeper protocol strengths/limitations (HTTP/HTTPS, WebSockets, AMQP, gRPC) and how they map to network stack layers.

---

What an API is (contract + boundaries)

An API (Application Programming Interface) functions as a contract between a client (browser/mobile) and a server.

The contract defines:

• Endpoints and HTTP methods
• Expected response shapes per endpoint

API benefits:

• Abstraction: hides implementation details while exposing functionality
• Service boundaries: enables separate systems (e.g., users service, posts service) to communicate without coupling

---

Main API Styles Compared

1) REST (resource-based, HTTP methods)

• Uses resource-based endpoints (e.g., /users, /posts).
• Stateless requests: each request carries what’s needed.
• CRUD mapping via HTTP methods:
  • GET fetch
  • POST create/store
  • PUT/PATCH update (PUT full replace vs PATCH partial)
  • DELETE remove
• Common in web/mobile apps.
• Versioning: explicit via /v1, /v2, …` and supports HTTP caching via headers.

2) GraphQL (single endpoint, client-specified shape)

• Single endpoint (commonly /graphql) for queries/mutations/subscriptions.
• Client requests exactly the fields needed via a query payload.
• Reduces round trips and avoids typical REST “overfetching/underfetching”.
• Suggested for complex UI and nested data views.
• Schema evolution: often field-level changes without versioning; can optionally version fields.
• Caching: emphasizes application-level caching rather than only HTTP caching.

3) gRPC (high-performance internal RPC)

• “Least common” among the three in general app development.
• RPC framework using Protocol Buffers.
• Transport: HTTP/2, enabling built-in streaming / bidirectional communication.
• Most suitable for microservices/internal server-to-server communication.
• Browser compatibility limitations are noted (HTTP/2 support dependency).

---

REST Design Principles + Best Practices (clean/consistent APIs)

Key principles:

• Consistency: naming conventions and patterns (e.g., avoid mixing camelCase and snake_case inconsistently).
• Simplicity: intuitive endpoints so developers can use the API without heavy documentation.
• Security: authentication + authorization, input validation, rate limiting.
• Performance:
  • caching strategies
  • pagination
  • minimal response payloads
  • reduce round trips (include additional needed data when appropriate)

REST resource modeling

• Use nouns not verbs:
  • /products (collection) vs /products/{id} (item)
  • avoid verb-ish paths like /getProducts
• Nested resources:
  • e.g., product reviews via /products/{id}/reviews

REST filtering/sorting/pagination

• Filtering and sorting via query parameters
• Pagination supports multiple patterns:
  • page + limit
  • offset + limit
  • cursor-based pagination
• Goal: reduce bandwidth and improve performance.

REST HTTP semantics (CRUD + status codes)

• GET should be safe/item-potent (same outcome on repeated calls, barring new data)
• POST creates (non-idempotent)
• PUT vs PATCH
  • PUT replaces whole resource
  • PATCH updates only specified fields
• Status codes emphasized:
  • 200/201/204 for success variants
  • 300 for redirects
  • 400 bad request / invalid input
  • 401 unauthorized
  • 404 not found
  • 500 server error

REST best practices recap

• plural nouns (e.g., /products)
• correct HTTP method usage (no fake /delete endpoint)
• support filtering/sorting/pagination
• explicit versioning with /api/v{n} to avoid breaking older clients

---

GraphQL Concepts + Best Practices

Why GraphQL exists:

• Created to solve REST client pain:
  • clients often need multiple API calls and still don’t get the exact data shape
• GraphQL:
  • single endpoint
  • client specifies response shape
  • reduces overfetching and latency from fewer requests

Schema & type system:

• Schema acts as a contract.
• Types mirror domain objects (e.g., User, Post).
• Queries for reading data (REST GET equivalent)
• Mutations for writing (REST POST/PUT/PATCH/DELETE equivalent conceptually)

Error handling differences:

• GraphQL often returns HTTP 200 even on errors
• Errors are placed into an errors field alongside partial data.
• Error objects can include status codes, messages, and paths.

GraphQL best practices:

• Keep schemas small and modular
• Avoid deeply nested queries; apply query depth limits
• Use meaningful naming for types/fields
• Use input types for mutations (for safer structured mutation payloads)

---

Authentication (who you are) — methods and key clarifications

Core distinction:

• Authentication answers: “Who is the requester?”
• Authentication happens before authorization; failed auth returns 401 Unauthorized.

Common confusion clarifications:

• JWT is a token format, not an authentication “method”.
• OAuth2 is an authorization framework, not authentication.
• Bearer is a pattern; JWT is typically the most common bearer token type.
• SSO is a user experience pattern, not an authentication mechanism.

Authentication methods covered:

• Basic auth: Base64 username/password (not secure unless HTTPS; outdated for production)
• Digest auth: MD5-based hashing (still outdated/rare)
• API keys:
  • unique key per client sent each request (e.g., X-API-Key)
  • stored as hashed values + scopes in DB
  • risk: if leaked, attackers can use it (unless you add expiration yourself)
• Session-based auth:
  • server stores session; client stores session cookie
  • scalable needs: use Redis or similar session store (not in-memory)
  • stateful: server must remember sessions
• Token-based auth (bearer tokens, often JWT):
  • stateless verification via signed JWT claims
  • described as scalable relative to sessions
  • includes access tokens (short-lived) and refresh tokens (long-lived)
  • refresh flow renews access tokens when access expires
  • refresh tokens stored in HTTP-only cookies (to reduce XSS risk)

OAuth2 + OpenID Connect:

• OAuth2 = authorization (delegated access to resources)
• OpenID Connect = adds authentication on top of OAuth2
  • introduces an ID token (JWT) containing identity claims (email/user id)

SSO & identity protocols:

• Single sign-on is UX: log in once to access multiple services.
• Uses identity protocols underneath:
  • SAML (older, XML-based; common in enterprise/legacy)
  • OpenID Connect (modern; JSON Web Token-based ID token)

---

Authorization (what you can do)

Core distinction:

• Authorization answers: “What resources/actions are allowed after authentication?”

Authorization models covered:

1. RBAC (Role-Based Access Control)
   • roles like admin/editor/viewer map to permissions
   • common example: GitHub-style repo permissions
2. ABAC (Attribute-Based Access Control)
   • policies based on user/resource/environment attributes (e.g., department + time + resource confidentiality)
   • more flexible but more complex policy management
3. ACL (Access Control Lists)
   • permissions attached to specific resources (user-centric)
   • flexible, but can be hard to scale at very large object/user counts
   • example cited: Google Drive sharing model

How OAuth2/JWT relate:

• OAuth2 and JWT act as enforcement mechanisms in flows:
  • OAuth2 provides delegated access tokens representing approved permissions
  • JWT/bearer tokens carry identity/claims; authorization logic uses roles/scopes/claims to permit actions

---

API Security: 7 techniques to protect APIs

1. Rate limiting
   • per endpoint, and optionally per user/IP
   • includes “overall” limits to mitigate botnets (many IPs/bots each within per-IP limits)
2. CORS
   • restricts which browser origins/domains can call the API
3. Injection protection (SQL/NoSQL injection)
   • use parameterized queries / ORM safeguards
4. Firewalls / WAF
   • block known malicious patterns (e.g., suspicious SQL keywords, abnormal methods)
5. VPN for internal/private APIs
   • restrict API access to authenticated network users (e.g., employees)
6. CSRF protection
   • for cookie-based auth systems
   • use CSRF tokens to ensure requests come from trusted origins
7. XSS mitigation
   • prevent script injection that later executes in other users’ browsers
   • described via malicious content stored in comments then rendered/executed

---

Next-step lesson mentioned

• The next lesson will cover deeper API protocols and their role in the network stack and transport layer:
  • application protocols: HTTP/HTTPS, WebSockets, AMQP
  • server RPC: gRPC
  • transport layer: TCP vs UDP selection guidance

---

Main speakers / sources

• Primary speaker: the course instructor narrating throughout (no specific name given in subtitles).
• Video organization/source: “How to Design APIs Like a Senior Engineer (REST, GraphQL, Auth, Security)” (implied course content; no additional named guest sources).