REST API Naming Conventions: What 72 APIs Do
Quick answer: Use lowercase nouns, plural for collections, and kebab-case when a segment needs two words: /order-items/{order_id}. Keep verbs out of paths and let the HTTP method carry the action. Put the version in the path if you version at all. Those are the conventions the majority of real public APIs actually follow, measured below.
Naming guidance for REST APIs is easy to find and almost never backed by evidence. Google, Microsoft and half a dozen style guides each publish a set of rules, and they disagree with each other on several of them. So we measured what shipped APIs do instead.
How we measured it
We took the public APIs listed in our directory, probed each one for a machine-readable OpenAPI document at the usual locations, and parsed every path out of the ones that answered. That produced 72 APIs, 3,852 endpoint paths and 10,551 path segments, including Notion, Razorpay, Resend, CircleCI, Hunter, OneSignal, Printify, Open Library, REST Countries and Postcodes.io.
Two things worth stating plainly. These paths come from spec documents, not from the documentation URLs we store, so they are real endpoints rather than marketing pages. And the sample skews modern: an API that publishes OpenAPI at a conventional location is better tooled than average, so read the numbers as "what careful teams do" rather than "what every API does".
Should REST resources be plural or singular?
Plural, by more than two to one. Of 1,694 collection segments that sit directly before a path parameter, 1,190 are plural (70.2%) and 504 are singular (29.8%). Counting one vote per API rather than per path gives the same answer: 38 APIs are majority-plural against 15 majority-singular.
So /users/{id} rather than /user/{id}. The practical argument is consistency: /users for the collection and /users/{id} for one member reads the same way at every level of nesting, while singular forces you to decide again for each endpoint.
kebab-case, snake_case or camelCase in a URL path?
Most segments are a single lowercase word and dodge the question entirely. Among the 1,408 segments that genuinely need two words:
| Style | Segments | Share |
|---|---|---|
| kebab-case (order-items) | 983 | 69.8% |
| snake_case (order_items) | 406 | 28.8% |
| camelCase (orderItems) | 18 | 1.3% |
One vote per API: kebab-case is dominant in 35 of the 72, snake_case in 14, camelCase in 2, and 21 APIs never use a multi-word segment at all.
camelCase in a path is effectively extinct. That matters because it is the one convention the style guides still argue about, and the market has already settled it. Hostnames are case-insensitive while paths are not, so a camelCase path is the segment most likely to be mistyped and 404.
The finding that surprised us: paths and parameters disagree
Within the same URL, real APIs switch conventions. Across 1,760 path parameters:
| Style | Parameters | Share |
|---|---|---|
| snake_case ({user_id}) | 916 | 52.0% |
| single word ({id}, {slug}) | 723 | 41.1% |
| camelCase ({userId}) | 121 | 6.9% |
| kebab-case ({user-id}) | 0 | 0% |
kebab-case wins the static segments and does not appear in parameters even once. snake_case wins the parameters. The result is that the most common shape in the wild is a mixed one: /order-items/{order_id}.
That is not sloppiness. Static segments are URL text, where hyphens are conventional and word separators are read by humans and search engines. Parameters are variable names that get bound to code, and no mainstream language allows a hyphen in an identifier. Pick kebab-case for the path and snake_case for the parameters, and you are agreeing with the largest group of shipped APIs.
How consistent are real APIs with themselves?
Less than you would hope. 17 of the 72 APIs (24%) use two or more casing styles inside their own URL space, and it is not always a stray endpoint: one API in the sample runs 21 snake_case segments next to a kebab-case one, another runs 14 kebab against 5 snake.
A rule you apply 80% of the time is worse than the rule you would have picked if you had written it down first. This is the one place where linting your spec in CI pays for itself immediately.
Should the version go in the path?
46% of the APIs (33 of 72) carry a version segment such as /v1/ in their paths. The rest either version through a header, version through the hostname, or do not version at all, which is the quiet majority position for small public APIs.
If you put it in the path, put it first and keep it to a major number: /v1/users, not /v1.2/users. If you never plan a breaking change, leaving it out is a defensible choice and easier to live with than a /v1/ you can never retire.
Should a URL ever contain a verb?
Almost never. 24 of the 72 APIs (33%) have at least one verb-first path like /getUser or /search-companies, but only one API in the sample is verb-first across the majority of its endpoints. The pattern survives as an exception for actions that are genuinely not resources, such as /search, /convert or /verify.
The rule that holds: the HTTP method is the verb, the path is the noun. POST /orders and not POST /createOrder. When an action truly has no resource behind it, a single verb segment at the end is the accepted escape hatch.
Small things the data settled
- Trailing slashes: only 5 of 72 APIs (7%) use them. Pick one form, redirect the other, and never make both canonical.
- File extensions in paths: 9 APIs still ship
.jsonor.xmlin the URL. Content negotiation through theAcceptheader is the modern answer, and this one is a legacy signal. /apias a prefix is common on APIs served from the same host as a website and unnecessary on a dedicatedapi.subdomain.
You can see all of this in the wild by opening any category in the directory and reading two or three specs side by side. The weather, geocoding and finance categories are good places to start, because they contain many APIs solving nearly identical problems with different naming.
FAQ
What is the difference between REST naming conventions and REST best practices? Naming conventions cover what you call things: path casing, plural versus singular, where the version goes. Best practices cover behaviour: status codes, pagination, errors, auth. We measured the behavioural side separately in REST API best practices.
Should JSON field names match the URL style? No, and most APIs do not make them match. URL segments trend kebab-case while JSON bodies trend either camelCase or snake_case depending on the ecosystem. Be consistent inside each layer rather than across them.
Should nested resources be nested in the URL?
One level is fine: /orders/{order_id}/items. Beyond that, prefer a flat path with a filter, because deep nesting bakes a hierarchy into your URLs that a later feature will break.
How do I name an endpoint that is an action, not a resource?
Model it as a sub-resource where you can, for example POST /orders/{order_id}/refunds. If that is a stretch, a single verb segment is acceptable. What you should avoid is a whole API built that way.
Do these conventions matter for AI agents and tooling? Yes, and more than they used to. Predictable, plural, lowercase paths are easier for a model reading your spec to generalise from, and a spec that mixes casing produces more wrong guesses. The same documentation discipline applies.