APIs are the connective tissue of modern software—every mobile app, web application, and AI agent depends on them to move data and trigger actions across systems. But the difference between an API that developers love and one that generates endless support tickets comes down to design decisions made before a single line of code is written.
APIs have always been critical, but in the age of AI-authored systems, they become even more so. With agents both writing and consuming software, the shift to API-first design (also sometimes referred to as spec-driven development) emphasizes a focus on architecture over syntax.
This guide will make sure you're designing APIs the right way for 2026: from RESTful fundamentals and authentication strategies to versioning, error handling, and building endpoints that AI agents can discover and use autonomously. Need a lighter intro before you dive deep? You can also check out our beginner's guide to using and integrating APIs.
At the end of the day, we know you don’t want to end up in this classic Reddit thread: What are some of the worst APIs you've ever had the displeasure of working with? Read on to learn how to avoid making API mistakes that make you famous in entirely the wrong way.
What is modern API design?
Modern API design is the practice of building programmatic interfaces that are easy to use, scalable, secure, and aligned with business goals. Rather than simply exposing data through endpoints, modern API design focuses on creating interfaces that developers actually want to integrate with—and increasingly, interfaces that AI agents can discover and use autonomously.
The shift from legacy to modern approaches comes down to intentionality. Older APIs often grew organically, with inconsistent naming, security added as an afterthought, and documentation that lagged behind the actual implementation. Modern API design flips this sequence: you define the contract and developer experience first, then build the implementation to match.
- Developer experience: Intuitive endpoints, predictable behavior, and clear documentation
- Security-first: Authentication and authorization baked in from day one
- Scalability: Stateless architecture that handles traffic spikes without rearchitecting
- AI-readiness: Structured responses that agents can parse, interpret, and act on
Want to see API building in action? Check out the below video for a primer.
Core API design principles
Before getting into specific patterns, it helps to understand the foundational principles that guide every decision—from URL structure to error messages.
Consistency and predictability
APIs that behave the same way across all endpoints are dramatically easier to learn. If one endpoint uses camelCase for field names, every endpoint uses camelCase. If one collection returns paginated results with `next` and `previous` links, all collections follow that same pattern.
Predictability reduces cognitive load. Developers can make accurate assumptions about unfamiliar endpoints based on their experience with familiar ones, which speeds up API integration and reduces support requests.
Simplicity over complexity
Fewer, well-designed endpoints typically outperform many specialized ones. A single /orders endpoint with filtering parameters is often more maintainable than separate endpoints for /pending-orders, /completed-orders, and /cancelled-orders.
Simpler APIs are easier to document, easier to test, and easier to evolve over time.
Security by default
Authentication, authorization, and input validation are never afterthoughts in modern API design. Role-based access control (RBAC) has become standard practice—users receive permissions based on their role, and the API enforces those permissions consistently across every request.
Platforms like Xano provide built-in RBAC and authentication, so security becomes part of the foundation rather than something layered on later.
Real-world failure: API authorization bugs at scale
Multiple high-profile breaches—including incidents at Coinbase and T-Mobile—have been traced back to APIs that allowed users to access resources they didn’t own. These cases highlight why authorization must be enforced at the object level inside every endpoint, not just at login time.
Backward compatibility
The principle here is straightforward: don't break existing clients. Changes extend existing behavior rather than altering it. Adding a new field to a response? Existing clients that don't expect it continue working. Deprecating a field? You provide a migration path and timeline, not a sudden removal.
RESTful API design fundamentals
REST (Representational State Transfer) remains the dominant architectural style for web APIs. GraphQL and gRPC have their place, but REST's simplicity and ubiquity make it the default choice for most applications.
Resource-oriented architecture
REST treats everything as a resource: users, orders, products, invoices. Each resource has a unique URI, and you interact with resources using standard HTTP methods. Resources are nouns, not actions—/users rather than /getUsers.
Stateless communication
Each request contains all the information the server requires to process it. The server doesn't store client session state between requests. This constraint enables horizontal scaling: any server instance can handle any request without needing to know what happened in previous requests.
Uniform interface constraints
REST defines four interface constraints that keep APIs consistent:
- Resource identification: URIs identify resources
- Manipulation through representations: Clients work with representations (usually JSON) of resources
- Self-descriptive messages: Requests include enough information (headers, media types) to be processed
- HATEOAS: Responses can include links to related resources and available actions
HATEOAS (Hypermedia as the Engine of Application State) is the most debated constraint. In practice, many production APIs implement it partially or skip it entirely, focusing instead on comprehensive documentation.
REST API endpoint naming conventions
URL structure is one of the first things developers notice about an API. Clear, predictable URLs signal a well-designed API; inconsistent URLs signal trouble ahead.
Use nouns for resource names
Endpoints represent things, not actions. The HTTP method indicates the action.
Use plural resource names
Consistency matters more than grammatical correctness. Always use /users rather than /user, even when retrieving a single user at /users/123. One rule is easier to remember than conditional rules.
Keep URLs flat and predictable
Deep nesting like /users/123/orders/456/items/789/notes becomes unwieldy quickly. Prefer shallower hierarchies, and consider whether nested resources could work as top-level resources with filtering instead.
Use query parameters for filtering and sorting
Keep the base URL clean and use query parameters for variations: /products?category=electronics&sort=-created_at. The minus sign prefix for descending sort is a common convention worth adopting.
HTTP methods and when to use them
Each HTTP method carries semantic meaning. Using methods correctly makes your API predictable and enables caching, retry logic, and other HTTP-level optimizations.
GET for retrieving resources
GET is safe (doesn't modify data) and idempotent (calling it multiple times produces the same result). Use GET for reading single resources or collections. GET requests can be cached and bookmarked.
POST for creating resources
POST creates new resources. It's not idempotent—calling it twice creates two resources. The response typically includes the created resource with its server-assigned ID.
PUT for full resource replacement
PUT replaces an entire resource with the payload you send. It's idempotent: sending the same PUT request multiple times results in the same final state. The client sends the complete resource representation.
PATCH for partial updates
PATCH updates specific fields without requiring the entire resource. It's the right choice when you're changing one attribute of a large object and don't want to resend everything.
For more on PUT vs. PATCH, check out these quick tips.
DELETE for removing resources
DELETE removes a resource. It's idempotent—deleting an already-deleted resource returns success (or 404, depending on your convention). Consider whether you want soft delete (marking as deleted) versus hard delete (actually removing the record).
API authentication best practices
Security is non-negotiable. Modern APIs typically implement one of several authentication patterns, depending on the use case and who—or what—is making requests.
OAuth 2.0 and OpenID Connect
OAuth 2.0 is the industry standard for delegated authorization—letting users grant limited access to their data without sharing credentials. OpenID Connect adds an identity layer on top. Both are the right choice for user-facing applications where you're authenticating humans through a browser or mobile app.
JSON Web Tokens for stateless auth
JWTs (JSON Web Tokens) contain encoded claims that can be verified without a database lookup. The server signs the token; clients include it in subsequent requests. The trade-off is revocation complexity—you can't easily invalidate a JWT before it expires without additional infrastructure like a token blacklist.
API keys for service-to-service communication
For server-to-server calls where there's no user context, API keys offer simplicity. They're essentially long-lived passwords, so they require HTTPS and regular rotation to stay secure.
Role-based access control
RBAC assigns permissions to roles, then assigns roles to users. A "viewer" role might have read-only access; an "admin" role might have full access. This approach scales better than assigning permissions directly to individual users.
Rate limiting and throttling
Rate limiting protects your API from abuse—whether malicious or accidental—and ensures fair usage across all clients. Without it, a single misbehaving client can degrade service for everyone else.
- Fixed window: Count requests per time period, like 100 requests per minute
- Sliding window: Smooths out bursts at window boundaries for more even distribution
- Token bucket: Allows controlled bursting while maintaining an average rate over time
Standard headers communicate limits to clients so they can adjust their behavior:
X-RateLimit-Limit: Maximum requests allowedX-RateLimit-Remaining: Requests left in current windowX-RateLimit-Reset: When the limit resets (Unix timestamp)
Real-world example: weak rate limiting results in mass scraping
In late 2025, researchers were able to scrape approximately 3.5 billion WhatsApp phone numbers by abusing the app’s contact-lookup API because it lacked meaningful rate limiting. Automated scripts could make millions of queries per hour without being throttled or blocked—turning a feature into a large-scale data harvesting vector. WhatsApp subsequently added protections to mitigate this class of abuse.
API versioning strategies
APIs evolve. Versioning lets you introduce breaking changes without disrupting existing clients who depend on the current behavior.
URI path versioning
The most common approach puts the version in the URL: /v1/users, /v2/users. It's visible, easy to understand, and simple to implement. The downside is that URLs change between versions, which can complicate caching and documentation.
Header versioning
The version lives in a custom header like API-Version: 2. URLs stay clean, but testing requires tools that can set headers—you can't just paste a URL into a browser to test it.
Query parameter versioning
Version as a parameter: /users?version=2. Flexible and easy to implement, but also easy to overlook. Less common in practice than URI versioning.
Versioning gone wrong
That said, naive versioning strategies can create more problems than they solve. CodexLab brings the real talk about their horror story: They tried to support v1 and v2 of their API by building a compatibility shim that translated between the two. But they only tested a few cases—in real traffic the shim returned 200 OK with empty bodies for many requests, so clients believed operations succeeded when they did nothing. Fixing this required emergency patches and rethinking how versions are mapped.
Pagination and filtering patterns
Any API returning collections benefits from pagination. Without it, a simple "list all users" request could return millions of records and overwhelm both server and client.
Cursor-based pagination
Cursor-based pagination uses opaque tokens rather than page numbers. It's better for real-time data where records might be added or deleted between requests. The cursor points to a specific position in the result set, so you always pick up where you left off.
Offset-based pagination
Offset-based pagination uses limit and offset parameters: /users?limit=20&offset=40. It's simpler to implement and understand, but can have performance issues with large offsets because the database still counts through all the skipped records.
Filtering and sorting parameters
Consistent conventions across endpoints improve developer experience significantly. Common patterns include ?filter[status]=active for filtering and `?sort=-created_at` for sorting, where the minus prefix indicates descending order.
REST API error handling
Good error responses help developers debug quickly. Bad error responses—generic messages, wrong status codes, missing details—waste everyone's time and generate support tickets.
Standard HTTP status codes
Use status codes correctly. They're the first thing a client checks when something goes wrong.
- 200 OK: Successful GET, PUT, PATCH
- 201 Created: Successful POST
- 204 No Content: Successful DELETE
- 400 Bad Request: Invalid input from the client
- 401 Unauthorized: Missing or invalid authentication
- 403 Forbidden: Authenticated but not authorized for this action
- 404 Not Found: Resource doesn't exist
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Server-side failure
Consistent error response format
Define a standard error schema and use it everywhere. Include enough detail for debugging without exposing sensitive internal information.
{
"error": "validation_error",
"message": "Email address is invalid",
"field": "email",
"code": "INVALID_EMAIL_FORMAT"
}Actionable error messages
"An error occurred" helps no one. "Email address is invalid—expected format: user@domain.com" tells developers exactly what to fix. The extra effort in crafting clear error messages pays off in reduced support burden.
API documentation with OpenAPI
OpenAPI (formerly Swagger) is the standard for describing REST APIs in a machine-readable format. The specification enables auto-generated documentation, client SDK generation, and request validation.
Documentation generated from an OpenAPI spec stays in sync with the actual API—a significant advantage over manually maintained docs that inevitably drift out of date. Modern backend platforms can auto-generate OpenAPI specs from your endpoint definitions, eliminating the documentation burden entirely.
For more tips about API documentation, check out What Is A Restful API Documentation Tool And Is It Right For Me?
Designing APIs for AI agents and MCP
Modern APIs increasingly serve AI agents alongside human-driven frontends. An agent-ready API goes beyond REST conventions to provide the context and discoverability that autonomous systems require to operate effectively.
Agent-friendly response structures
Consistent, predictable JSON schemas help agents parse responses reliably. Avoid deeply nested structures when flatter alternatives exist. Include metadata that helps agents understand context—pagination info, resource types, and available actions.
Model Context Protocol endpoints
MCP (Model Context Protocol) is a standard for exposing backend capabilities to AI agents. Unlike REST, MCP endpoints include machine-readable metadata and natural language descriptions that help agents discover what's available and decide how to use it.
Xano's MCP Builder lets you create agent-compatible endpoints alongside traditional REST APIs, so your backend serves both human-driven applications and autonomous agents from a single source of truth.
Idempotency for safe retries
AI agents may retry requests due to timeouts or uncertainty about whether a previous request succeeded. Idempotency keys ensure that duplicate requests don't cause duplicate actions—critical for payment flows, state changes, and any operation where "doing it twice" would cause problems.
Real-world impact
In practice, missing idempotency protections have caused significant issues. For example, a payment API used by Uber Eats in India once lacked proper idempotency logic; retries and connection failures allowed orders to be placed without charging users, costing the business thousands of dollars before the problem was resolved.
Build production-ready APIs without the infrastructure overhead
Applying modern API design patterns doesn't require building everything from scratch. Platforms like Xano embed these patterns by default—visual logic for building endpoints, built-in authentication and RBAC, managed Postgres with relationships and triggers, and auto-scaling infrastructure that grows with your traffic.
The goal is focusing on product logic rather than managing servers, writing boilerplate auth code, or stitching together separate tools for database, API, and infrastructure. Whether you're building for a mobile app, a web frontend, or an AI agent, a unified backend keeps your architecture maintainable as you scale.
FAQs about modern API design
What is the difference between REST and GraphQL for API design?
REST uses fixed endpoints that return predefined data structures. GraphQL uses a single endpoint where clients specify exactly what fields they want returned. REST is simpler and more cacheable; GraphQL reduces over-fetching but adds query complexity. The right choice depends on your use case—REST works well for most applications, while GraphQL shines when clients have highly variable data requirements.
How do APIs handle breaking changes without disrupting clients?
Versioning is the primary approach. Introduce breaking changes in a new version (/v2/) while maintaining the old version with a clear deprecation timeline. Communicate changes through documentation, changelogs, and deprecation headers. Give clients time to migrate rather than forcing immediate updates.
What is the Richardson Maturity Model?
The Richardson Maturity Model describes four levels of REST API maturity. Level 0 uses HTTP as transport only. Level 1 introduces resources. Level 2 adds proper HTTP methods and status codes. Level 3 implements full HATEOAS with hypermedia controls. Most production APIs operate at Level 2—Level 3 adds complexity that many teams find unnecessary for their use cases.
