API design

Ensures predictable, self-documenting URI structures that reduce cognitive load for API consumers and enable consistent client code generation.

REST API design: defining resource paths for a new microservice; API review: auditing existing endpoints for consistency across teams; OpenAPI/Swagger documentation: establishing patterns for spec generation and SDK scaffolding

REST APIs, microservices, OpenAPI/Swagger specs, web frameworks (Express, FastAPI, Spring Boot, Django REST), API gateways

pluralized-noun resource paths with hierarchical sub-resources and consistent casing (kebab-case or camelCase)

• REST resource modeling
• HTTP method semantics
• URI path parameters
• API versioning strategies
• OpenAPI specification
• pluralized resource nouns

• RPC-style action endpoints (tighter coupling
• less RESTful)
• verb-based URLs like /getUser (conflates URI with HTTP method semantics)
• query parameters for filtering (complements but does not replace path conventions)

Mixing singular and plural nouns across endpoints (e.g. /user vs /orders) — breaks client expectations and indicates inconsistent modeling; using verbs in resource paths (e.g. /createOrder instead of POST /orders) — duplicates HTTP method semantics inside the URI; deep nesting beyond 2-3 levels (e.g. /orgs/{id}/teams/{id}/projects/{id}/tasks/{id}) — signals a missing abstraction layer; inconsistent casing (camelCase vs snake_case vs kebab-case) — breaks URL parsing and client code generation; exposing implementation details in paths (e.g. /api/v2/db/users) — couples the public API to internal architecture

Resource modeling (defines WHAT endpoints exist, not how they are named); HTTP method semantics (defines WHAT operations endpoints support); URI vs URL distinction (URI is the identifier, URL includes the access mechanism)

Coming from RPC/SOAP: may use verb-based action endpoints (getUser, createOrder) — REST conventions use noun-based resources with HTTP methods encoding the action; Coming from filesystem paths: may use deep hierarchical nesting — REST favors shallow, resource-oriented paths that reflect domain entities not directory structure

• REST resource modeling
• HTTP method semantics
• API versioning
• URI design patterns
• OpenAPI specification

When NOT to use: for internal RPC-style services where action-oriented endpoints are clearer and more direct; Performance: longer paths add negligible overhead but complicate caching rules; Boundary conditions: path parameters must be URL-safe, casing must be uniform across the entire API surface, and reserved characters require percent-encoding

Well-designed endpoint naming lets client developers predict endpoint structure without consulting docs, shortens onboarding time, and makes API evolution safer by establishing clear patterns for adding new resources.

Like street addresses in a well-planned city: consistent naming (numbered streets, predictable suffixes) lets visitors navigate without a map, while chaotic naming forces everyone to carry directions.

HATEOAS and hypermedia-driven API design; API versioning strategies (URI vs header vs content-type); GraphQL schema design conventions