Skip to main content

Learning path

API Design & Architecture learning path: everything to study, topic by topic

Comprehensive API design assessment covering REST fundamentals, resource modeling, authentication and security, documentation with OpenAPI, versioning strategies, advanced patterns (GraphQL, gRPC, webhooks), caching, API gateways, and governance.

Short answer

To learn API Design & Architecture, work through 6 modules and 22 topics in the order they build on each other. It starts with REST Fundamentals, then moves on to API Design Principles and Authentication & Security. Use the map as a checklist, or measure your level and study only what is missing.

6
modules
22
topics
45
min to assess

What you will study

Topics are grouped by module. Open one to see its objectives and key concepts.

1 · REST Fundamentals4 topics
  • HTTP Methods

    GET, POST, PUT, PATCH, DELETE semantics, idempotency guarantees, safe vs unsafe methods, HEAD and OPTIONS, method selection guidelines

    Objectives

    • Select the correct HTTP method for each CRUD operation
    • Explain idempotency and its implications for API design

    Key concepts

    • GET for retrieval
    • POST for creation
    • PUT for full replacement
    • PATCH for partial update
    • DELETE for removal
    • idempotency
    • safe methods
    • HEAD and OPTIONS
  • HTTP Status Codes

    1xx informational, 2xx success, 3xx redirection, 4xx client errors, 5xx server errors, choosing appropriate codes, common anti-patterns

    Objectives

    • Choose the correct status code for API responses
    • Distinguish between 401 Unauthorized and 403 Forbidden

    Key concepts

    • 200 OK
    • 201 Created
    • 204 No Content
    • 400 Bad Request
    • 401 vs 403
    • 404 Not Found
    • 409 Conflict
    • 429 Too Many Requests
  • URL Design

    Resource naming conventions, plural vs singular nouns, hierarchical paths, query parameters, path parameters, URI structure best practices

    Objectives

    • Design clean and consistent API URLs
    • Decide between path and query parameters

    Key concepts

    • plural nouns for collections
    • nested resources
    • path parameters
    • query parameters
    • kebab-case vs snake_case
    • avoiding verbs in URLs
    • resource hierarchy depth
    • URI length limits
  • Request & Response Formats

    JSON structure, content negotiation, Accept and Content-Type headers, envelope patterns, field naming conventions, data types in JSON

    Objectives

    • Structure consistent JSON request and response bodies
    • Apply content negotiation headers correctly

    Key concepts

    • JSON as default format
    • Content-Type header
    • Accept header
    • camelCase vs snake_case fields
    • ISO 8601 dates
    • envelope pattern
    • null handling
    • data type consistency
2 · API Design Principles4 topics
  • Resource Modeling

    Identifying resources from domain models, sub-resources, resource relationships, composite resources, action resources for non-CRUD operations

    Objectives

    • Model API resources from business domain concepts
    • Design action endpoints for operations that do not map to CRUD

    Key concepts

    • domain-driven resource identification
    • sub-resources
    • resource relationships
    • composite resources
    • action endpoints
    • singleton resources
    • resource granularity
    • avoiding CRUD-only thinking
  • Pagination & Filtering

    Offset-based pagination, cursor-based pagination, page-based pagination, filtering query parameters, sorting, field selection, search endpoints

    Objectives

    • Choose the right pagination strategy for different data sets
    • Design consistent filtering and sorting query parameters

    Key concepts

    • offset/limit pagination
    • cursor-based pagination
    • page/per_page pagination
    • sort parameters
    • filter query syntax
    • field selection (sparse fieldsets)
    • search endpoints
    • pagination metadata
  • Error Handling

    Error response format, RFC 7807 Problem Details, error codes, validation errors, error message localization, error aggregation

    Objectives

    • Design a consistent error response format following RFC 7807
    • Return actionable error messages without leaking internals

    Key concepts

    • RFC 7807 Problem Details
    • error code taxonomy
    • validation error arrays
    • field-level errors
    • error message i18n
    • stack trace exclusion
    • error aggregation
    • retry guidance in errors
  • HATEOAS & Hypermedia

    Hypermedia as the Engine of Application State, link relations, HAL format, JSON:API links, discoverability, Richardson Maturity Model

    Objectives

    • Explain the Richardson Maturity Model levels
    • Add hypermedia links to API responses for discoverability

    Key concepts

    • HATEOAS principle
    • link relations (self, next, prev)
    • HAL format
    • JSON:API links
    • Richardson Maturity Model
    • API discoverability
    • hypermedia controls
    • link templating
3 · Authentication & Security4 topics
  • Authentication Mechanisms

    API keys, OAuth 2.0 flows, JWT structure and validation, bearer tokens, basic auth, session vs token authentication, OIDC

    Objectives

    • Choose the appropriate authentication mechanism for different API consumers
    • Explain OAuth 2.0 authorization code flow end to end

    Key concepts

    • API keys
    • OAuth 2.0 authorization code flow
    • OAuth 2.0 client credentials
    • JWT structure (header, payload, signature)
    • bearer tokens
    • token refresh flow
    • OpenID Connect
    • basic authentication
  • Authorization Patterns

    Role-based access control (RBAC), attribute-based access control (ABAC), scopes, permissions, resource-level authorization, policy engines

    Objectives

    • Design an authorization model that supports multi-tenancy
    • Distinguish between authentication and authorization in API design

    Key concepts

    • RBAC
    • ABAC
    • OAuth 2.0 scopes
    • fine-grained permissions
    • resource-level authorization
    • policy engines (OPA)
    • API key scoping
    • multi-tenancy authorization
  • API Security Best Practices

    OWASP API Security Top 10, input validation, CORS, TLS, injection prevention, sensitive data exposure, mass assignment

    Objectives

    • Apply OWASP API Security Top 10 mitigations
    • Configure CORS policies correctly for API consumers

    Key concepts

    • OWASP API Security Top 10
    • input validation
    • CORS configuration
    • TLS/HTTPS enforcement
    • injection prevention
    • sensitive data in responses
    • mass assignment protection
    • security headers
  • Rate Limiting & Throttling

    Token bucket algorithm, sliding window, fixed window, rate limit headers, quota management, burst handling, per-client limits, 429 responses

    Objectives

    • Design a rate limiting strategy with appropriate headers
    • Compare token bucket and sliding window algorithms

    Key concepts

    • token bucket algorithm
    • sliding window counter
    • fixed window counter
    • X-RateLimit headers
    • Retry-After header
    • per-client quotas
    • burst allowance
    • tiered rate limits
4 · Documentation & Versioning3 topics
  • OpenAPI Specification

    OpenAPI 3.x structure, paths, schemas, components, request/response definitions, code generation, Swagger UI, API-first design

    Objectives

    • Write an OpenAPI specification for a RESTful API
    • Apply API-first design by starting with the specification

    Key concepts

    • OpenAPI 3.x structure
    • paths and operations
    • schema definitions
    • components and reusability
    • request body definitions
    • response definitions
    • code generation from spec
    • API-first design workflow
  • API Versioning

    URL path versioning, header versioning, query parameter versioning, content negotiation versioning, semantic versioning for APIs, version sunsetting

    Objectives

    • Choose an API versioning strategy and justify the trade-offs
    • Identify breaking vs non-breaking changes in an API

    Key concepts

    • URL path versioning (/v1/)
    • header versioning (Accept)
    • query parameter versioning
    • content negotiation
    • semantic versioning
    • breaking vs non-breaking changes
    • version coexistence
    • sunset header
  • Changelog & Deprecation

    API changelog management, deprecation policies, sunset headers, migration guides, consumer communication, backward compatibility strategies

    Objectives

    • Design a deprecation policy with clear timelines and communication
    • Manage API evolution while maintaining backward compatibility

    Key concepts

    • changelog formats
    • deprecation warnings
    • Sunset header (RFC 8594)
    • migration guides
    • consumer notification
    • backward compatibility
    • grace periods
    • usage analytics for deprecation
5 · Advanced Patterns5 topics
  • GraphQL APIs

    Schema definition language, queries, mutations, subscriptions, resolvers, N+1 problem, DataLoader, federation, REST vs GraphQL trade-offs

    Objectives

    • Design a GraphQL schema with proper type definitions
    • Compare REST and GraphQL trade-offs for different use cases

    Key concepts

    • schema definition language (SDL)
    • queries and mutations
    • subscriptions
    • resolvers
    • N+1 problem
    • DataLoader pattern
    • federation
    • REST vs GraphQL trade-offs
  • gRPC & Protocol Buffers

    Protocol Buffers schema, service definitions, unary and streaming RPCs, gRPC vs REST, bidirectional streaming, error model, gRPC-Web

    Objectives

    • Define protobuf messages and gRPC services
    • Choose between REST, GraphQL, and gRPC for different scenarios

    Key concepts

    • Protocol Buffers (protobuf)
    • service definitions
    • unary RPC
    • server streaming
    • client streaming
    • bidirectional streaming
    • gRPC error model
    • gRPC-Web for browsers
  • Webhooks & Event-Driven APIs

    Webhook design, event payload structure, delivery guarantees, retry policies, signature verification, event schemas, SSE, WebSocket APIs

    Objectives

    • Design a webhook system with reliable delivery and signature verification
    • Compare webhooks, SSE, and WebSocket for real-time API communication

    Key concepts

    • webhook registration
    • event payload design
    • delivery guarantees
    • retry with exponential backoff
    • HMAC signature verification
    • event schema versioning
    • Server-Sent Events (SSE)
    • WebSocket APIs
  • Caching & Performance

    HTTP caching headers, ETags, conditional requests, CDN integration, cache invalidation strategies, API response compression, connection pooling

    Objectives

    • Implement HTTP caching with proper headers and conditional requests
    • Design a cache invalidation strategy for APIs

    Key concepts

    • Cache-Control header
    • ETag and If-None-Match
    • Last-Modified and If-Modified-Since
    • CDN cache layers
    • cache invalidation strategies
    • response compression (gzip, br)
    • connection pooling
    • 304 Not Modified
  • API Gateways

    Gateway patterns, request routing, load balancing, request transformation, aggregation, circuit breaker, service mesh integration

    Objectives

    • Design an API gateway layer with routing, rate limiting, and auth
    • Compare API gateway and service mesh approaches

    Key concepts

    • API gateway pattern
    • request routing
    • load balancing
    • request/response transformation
    • API aggregation (BFF)
    • circuit breaker
    • service mesh integration
    • gateway vs service mesh
6 · API Governance2 topics
  • API Standards & Style Guides

    API style guides, naming conventions enforcement, linting rules, design review processes, API catalog, developer portal, SDK generation

    Objectives

    • Create an API style guide that enforces consistency across teams
    • Set up automated API linting with Spectral or similar tools

    Key concepts

    • API style guide authoring
    • spectral linting rules
    • design review process
    • API catalog and registry
    • developer portal
    • SDK auto-generation
    • API design patterns library
    • consistency enforcement
  • API Lifecycle Management

    API-as-a-product, lifecycle stages, API maturity model, platform strategy, monetization, partner ecosystem, API metrics and KPIs

    Objectives

    • Define API KPIs and measure API program success
    • Design an API platform strategy with monetization and partner ecosystem

    Key concepts

    • API-as-a-product mindset
    • API lifecycle stages
    • API maturity model
    • platform strategy
    • API monetization models
    • partner and ecosystem APIs
    • API KPIs and metrics
    • API program management

Levels: Junior, Mid, Senior, and Expert

Explain it in your own words

Graded by AI · no account · 1 question

No options to guess from: you write, the AI grades against the topic's rubric and tells you what level your answer reads at.

0 / 600

Already studying API Design & Architecture?

The assessment measures topic by topic, and your plan skips what you already know.

Measure my level

Open to read. An account is only needed to be measured.

Frequently asked questions

Where should I start studying API Design & Architecture?

Start with REST Fundamentals: HTTP Methods, HTTP Status Codes, and URL Design. The map orders topics by what they depend on, so each one prepares the next.

How long does a full API Design & Architecture assessment take?

A full assessment of this path takes about 45 minutes. Study time depends on where you start; a diagnostic shows which topics you can skip.

Do I need an account to use this page?

No. The map, objectives and key concepts are open. You only need an account to be measured, get your gap by topic and receive a plan.