REST API Naming Conventions: A 2026 Reference
A REST API’s naming conventions are the invisible UX that shapes whether your API feels obvious or annoying. The choices look small (plural or singular, camelCase or snake_case, id or userId) but they accumulate. Get them right and developers integrating with your API rarely consult the docs. Get them wrong and every team that touches your API runs into the same friction.
This reference covers the conventions that hold up across modern REST APIs in 2026: resource paths, HTTP methods, path vs query parameters, JSON field names, versioning, and the additional considerations that matter when AI agents consume the same API through MCP.
Why REST API naming conventions matter
Naming is the part of API design that compounds the most. A name lives forever in client SDKs, in customer integrations, in your support tickets, in third-party documentation that referenced your API. Renaming a field after launch is a breaking change, which means the cost of fixing a bad name later is roughly the cost of shipping a new major version. Most teams underestimate this until they ship their second major version and realize the migration touched dozens of customer codebases.
There is no single “official” REST naming standard. Roy Fielding’s REST dissertation defined the architectural style but not the naming conventions; those evolved through practice over the last two decades. The conventions in this guide are the ones every modern public API converges on (Stripe, Twilio, GitHub, OpenAI), not because they are mandated, but because they minimize surprise for the developer reading your spec. A developer who has integrated three APIs that follow these conventions can integrate a fourth one in half the time.
The rules that hold across every REST API
Six rules show up in every modern naming convention:
- Use nouns for resources, not verbs.
/orders, not/getOrders. The HTTP method is the verb. Stripe’s/v1/charges, GitHub’s/repos, and OpenAI’s/v1/chat/completionsall follow this pattern. - Plural nouns for collections, singular for items.
/ordersfor the collection,/orders/42for one order. The exception is singletons (/me,/health) where there is only ever one instance. - Lowercase only in URLs. No camelCase or PascalCase in paths. URLs are technically case-sensitive per RFC 3986, but lowercase is the universal expectation. Stripe’s
/payment_intents(snake_case but lowercase) and Twilio’s/messagesboth honor this. - Hyphens separate words in URLs.
/order-details, not/orderDetailsor/order_details. Stripe is the notable exception here, using snake_case in paths to match their JSON convention; pick one strategy and apply it consistently. - kebab-case in URLs, camelCase or snake_case in JSON bodies. Pick one for JSON and stick with it. Stripe uses snake_case for JSON keys; OpenAI and Twilio use snake_case; GitHub uses snake_case; AWS uses PascalCase. The choice is convention-driven, not technical.
- Be consistent within your API. Whatever choices you make, apply them everywhere. Inconsistency is worse than any specific convention. An API with some camelCase fields and some snake_case fields will produce client SDKs full of awkward conversion code.
Following these six rules covers most naming decisions before any deeper thinking.
Resource naming (plurals, hierarchy, depth)
The two questions that come up most often:
Plural or singular? Plural for collections (/customers), singular through the resource identifier (/customers/123). The path /customer/123 is unusual and signals to consumers that the convention is inconsistent.
How deep should nesting go? Two levels is the practical maximum. /customers/123/orders is fine. /customers/123/orders/456/items/789 is a design smell. When you reach for three levels, you usually want a top-level resource with filter parameters instead: /items?orderId=456.
A few related practices:
- Use the resource ID directly in the path:
/users/123, not/users/show/123. - For actions that do not fit CRUD (search, login, send-email), POST to a named endpoint:
/searches,/sessions,/messages. REST purists will tell you to model these as resources; in practice, naming the endpoint after the action is acceptable for non-CRUD operations. - For relationships that are not strict containment, use a sub-resource path:
/users/123/followersis clearer than/followers?userId=123.
Resource naming choices show up in our broader API design principles as one of the decisions that compounds across an API’s lifetime.
HTTP method conventions
The method is the verb. The URL identifies the resource. The method tells the server what to do with it. Our API methods reference covers each verb in detail.
| Method | Use | Idempotent? |
|---|---|---|
| GET | Retrieve | Yes |
| POST | Create | No |
| PUT | Replace entirely | Yes |
| PATCH | Partial update | Sometimes |
| DELETE | Remove | Yes |
The mistake to avoid: putting the verb in the URL. POST /createUser is wrong; the method already says “create.” POST /users is right.
For non-CRUD actions that do not fit cleanly into the method/resource pattern, use POST to a named endpoint. POST /sessions for login is conventional and well-understood, even though “session” is being treated as a resource rather than an action.
Path parameters vs query parameters
Path parameters identify a specific resource. Query parameters modify a request.
- Path parameter (identifies):
/orders/42tells the server which order. - Query parameter (filters or modifies):
/orders?status=paid&limit=20tells the server which subset of orders to return.
The rule that follows from this: do not put filters in the path, and do not put resource IDs in the query string. /orders/status=paid and /orders?id=42 are both anti-patterns. The first turns a filter into a fake resource; the second loses the ability to use HTTP caching on a specific resource URL.
Path parameter names follow the resource naming convention (lowercase, hyphens, no verbs). Query parameter names typically use camelCase or snake_case to match the JSON field names of the resource: ?customerId=123 or ?customer_id=123. Pick the same convention you use in JSON.
A few common query parameter names that have crystallized into convention across major APIs:
- Pagination:
limitandoffset, orpage_sizeandpage, orcursorfor cursor-based pagination. Stripe uses cursor-based; Twilio uses page-based; choose one and document the choice. - Filtering: the field name being filtered, e.g.,
?status=paid&customer_id=123. Stay away from generic?filter=...query strings; they push parsing complexity onto consumers. - Sorting:
sort=created_atorsort=-created_at(the minus sign for descending order is a well-understood convention). - Field selection:
?fields=id,name,emaillets consumers request only the fields they need. Useful for mobile and bandwidth-constrained clients.
JSON field naming (camelCase vs snake_case)
The single biggest unresolved debate in REST naming. There is no objectively correct answer; there are popular conventions:
- camelCase is the conventional default in JavaScript and Java codebases. Used in GitHub’s GraphQL API and many JavaScript-first public APIs.
- snake_case is the Python and Ruby default. Stripe, OpenAI, and GitHub’s REST API use it, as do Slack, Twilio, and many older APIs from the JSON era.
- kebab-case is occasionally seen in JSON keys but causes friction in most languages (it cannot be a property name in JavaScript without quoting), so avoid it in JSON bodies.
Pick one and apply it across every endpoint. Mixing camelCase and snake_case in the same API is the kind of inconsistency developers complain about for years.
For field names specifically:
- Use full words, not abbreviations.
descriptionoverdesc.customerovercust. Abbreviations save four characters and cost years of “what does this field mean?” questions. - Be explicit about types in the field name when ambiguity matters.
expiresAt(timestamp) is clearer thanexpires.isActive(boolean) is clearer thanactive.priceCents(integer) is clearer thanpricewhen you have decided to store money as integer cents. - For IDs, use the parent resource name as a prefix when the field appears in a child resource:
customerIdon an Order is clearer thanid. The plainidfield is reserved for the resource the JSON itself represents. - For timestamps, use ISO 8601 strings (
"2026-05-22T14:30:00Z"), not Unix epoch integers or human-readable strings. Every modern API and language has a parser for ISO 8601; ambiguous formats produce parsing bugs. - For enum-style fields, use lowercase strings, not integers.
"status": "paid"survives schema migrations better than"status": 2. The string is also self-documenting in logs.
Versioning, deprecation, and the URL
Three conventions hold across the major API styles:
- URI versioning (
/v1/orders,/v2/orders) is the most common and most consumer-friendly. The version is visible in the URL; routing and caching just work. - Header versioning (
Accept: application/vnd.company.v1+json) is cleaner but harder for the consumer to debug. Used by GitHub and a few other large APIs. - Query string versioning (
/orders?version=1) is rare and not recommended; it blurs the line between versioning and filtering.
For deprecation, use the IETF-standard Sunset response header (RFC 8594) paired with the Deprecation response header (RFC 9745). Well-behaved SDKs warn developers automatically when they see them.
The naming decision that compounds the most: state the version naming policy in your developer portal on day one. Without a public policy, every breaking change becomes a negotiation.
Naming conventions for AI-agent-consumable APIs
Three additional considerations matter when the consumer is an AI agent rather than a human developer.
operationId in the OpenAPI spec is now user-facing copy. Agents read the operationId, summary, and description of every endpoint to decide which one to call. Vague or generic descriptions cause wrong tool selection. Treat these fields the same way you treat a feature name in a developer portal: specific, distinctive, unambiguous.
Idempotency-Key header support is now naming convention. Agents retry aggressively. For every POST and PATCH, accept an Idempotency-Key header and document it in the OpenAPI spec. The convention name (Idempotency-Key) is what agents look for; using a different header name (e.g., X-Request-Id) breaks compatibility with agent libraries.
Endpoint names should reflect the intent the agent will invoke. POST /messages is clearer to an agent than POST /msg-send or POST /communication. The endpoint name should map to a verb the agent might form (“send a message”) without much translation. Stripe’s POST /v1/charges and OpenAI’s POST /v1/chat/completions both pass this test: the path tells the agent exactly what kind of resource it is about to create.
Tags in the OpenAPI spec group related endpoints for agents. When an agent loads your spec, the tags field organizes endpoints into navigable groups. Use semantic tags (Payments, Customers, Webhooks) rather than internal-team naming (team-platform-v2). Agents do not have organizational context; they will treat your tags as user-facing categories.
The WSO2 AI Gateway auto-generates an MCP server from any OpenAPI spec. The better the names in the spec, the better the agent experience without a separate build. Specs written with vague descriptions and team-internal tags produce agents that pick the wrong endpoint roughly as often as they pick the right one.
Common REST API naming mistakes to avoid
A short catalog of the patterns that cause the most pain in production. These come up in API reviews repeatedly and are worth scanning for before shipping.
Singular collection names. /order instead of /orders, /user instead of /users. The plural form scales to “list of orders” and “one order at /orders/42” without any awkwardness. Singular collection names force you to invent special paths for the list operation.
Verbs in URLs. POST /createUser, GET /listOrders, POST /deleteAccount. The HTTP method already says what the operation is; the URL identifies the resource. Verbs in the URL duplicate what the method conveys and break the consistency every REST consumer expects.
Mixing casing styles in URLs. /orderDetails next to /order-items next to /order_logs. Pick one URL casing convention (kebab-case is the most common for paths) and apply it across every endpoint. Mixed casing in URLs is the most visible naming inconsistency and frequently the first thing reviewers complain about.
Inconsistent JSON field naming. customer_id in one endpoint, customerId in another, CustomerID in a third. Pick one casing for JSON (camelCase or snake_case; both are valid) and never mix them. SDK generators produce ugly output across mixed conventions, and consumers waste time looking up the spelling for each endpoint.
Pluralizing the wrong noun. /childrens (the plural of “child” is “children”), /peoples (the plural of “person” is “people”), /datas (the plural of “data” is “data”). Use correct English plurals; the URL is part of the developer-facing surface and odd plurals signal a careless API.
Over-deep nesting. /companies/{companyId}/users/{userId}/orders/{orderId}/items/{itemId}/comments/{commentId} is six levels deep. Two levels is the practical maximum (/companies/{companyId}/users/{userId} is the limit). For deeper relationships, use top-level resources with filter parameters (/items?orderId=...).
Inconsistent ID formats across endpoints. Some endpoints return integer IDs, some return UUIDs, some return prefixed strings (cust_123). Pick a convention (typed prefixed IDs scale well for multi-resource APIs) and apply it everywhere. Mixed ID formats break SDK type safety and force consumers to write per-endpoint parsing code.
Acronyms in inconsistent case. userId vs. userID, apiKey vs. APIKey, URLPath vs. urlPath. Pick a style for acronyms (most modern style guides recommend treating them as words: userId, apiKey, urlPath) and apply it across both URLs and JSON.
Reserved-word collisions. class, type, for, default. These are reserved or near-reserved words in many languages. SDK generators handle them, but the generated code looks awkward (class_, _default). Prefer specific names (category over class, kind over type) where the meaning allows.
URL paths that leak implementation detail. /api/v1/getOrdersByCustomerIdSorted exposes the implementation; /customers/{id}/orders?sort=... is the consumer-facing shape. The URL should reflect the consumer’s view of the resource model, not the database schema or the internal handler name.
Plural-vs-collection ambiguity. /auth and /authentication mean roughly the same thing. /billing and /payment overlap. /usage and /metrics overlap. Pick one canonical name per concept and use it everywhere; allowing two names creates SDK and documentation duplication.
Path segments that depend on query parameters to be meaningful. A path like /items that returns wildly different shapes depending on ?type=order_item vs ?type=invoice_item is two resources pretending to be one. Split them into /order-items and /invoice-items.
These are not exhaustive, but they cover the bulk of naming-related comments in real API reviews. Catching them at design time (or in spec linting) is the cheapest way to prevent them.
How Moesif and WSO2 enforce naming conventions in production
The hard part of naming conventions is not picking them. It is enforcing them across an organization that ships dozens of APIs.
WSO2 API Manager runs governance policies against the OpenAPI spec at merge time. Naming rules (plural collections, kebab-case paths, camelCase JSON, no verbs in URLs) become automated checks that fail builds before the API ships. New APIs inherit the rules; existing APIs flag violations during the next migration.
Once the API is live, Moesif observes whether the conventions hold up in practice. When customer code calls endpoints with unexpected case-sensitivity or sends fields with the wrong casing, Moesif’s logs surface the pattern across customers, not just one ticket at a time.
The integrated stack covers the design-time enforcement (WSO2) and the runtime observation (Moesif), which is the loop most teams are missing.
Next steps
Good naming costs nothing at design time and is impossible to fix after launch without breaking changes. Get the conventions written down before the first endpoint goes live and enforce them with automated governance.
If you want to see whether the naming conventions your API ships with are actually being used the way you expect, start a 14-day Moesif free trial for per-endpoint, per-customer analytics in production. No credit card required.
Frequently asked questions
What are REST API naming conventions? The standard practices for naming resources, endpoints, HTTP methods, path and query parameters, and JSON fields in a REST API. They cover plurals, casing, hierarchy, versioning, and special cases like non-CRUD actions.
Should REST API endpoints use plural or singular nouns? Plural for collections (/orders), singular for individual resources accessed by ID (/orders/42). Mixing these is the most common naming inconsistency.
Is camelCase or snake_case better for REST API JSON fields? Neither is objectively better. camelCase is the JavaScript and Java default in source code; snake_case is the Python and Ruby default. Several major public APIs (Stripe, OpenAI, GitHub’s REST API, Slack, Twilio) use snake_case for JSON keys regardless of the implementing language. Pick one for your API and apply it everywhere.
Should REST URLs be lowercase? Yes. URLs are case-sensitive per RFC 3986, but lowercase is the universal convention. Mixed case in paths is treated as a design error by most API governance tools.
How do I name actions that don’t fit CRUD? POST to a named endpoint that describes the action: POST /searches, POST /sessions, POST /messages/send. REST purists prefer modeling these as resources; in practice, both styles are used widely.
Should I version REST APIs in the URL or in headers? URL versioning (/v1/orders) is the most common in 2026 because it is the most consumer-friendly. Header versioning is cleaner but harder for developers to debug. Whichever you pick, publish your deprecation policy on day one.
Related Articles
API Strategy
Leveraging AI For a Better API Strategy
Learn how to leverage AI to build and fortify your API strategy. Improve design, governance, documentation, and align APIs with business outcomes.
API Strategy
The 5 Best Mixpanel Alternatives of 2025
Learn about the best Mixpanel alternatives to determine the right analytics solution for your use case.
API Development
How to Leverage Moesif Effectively for API Observability
Effectively leverage Moesif for API observability through best practices for integration, event enrichment, custom actions, and engineering workflow integrat...
API Strategy
How to Build an Internal Chargeback Model for Your API and AI Usage Using Moesif
Use Moesif to implement internal chargebacks and enable precise API and AI cost attribution for better transparency and resource optimization.