Why is a consistent naming convention crucial in REST API endpoints?

Consistent naming conventions make your API predictable, easier to understand, and use. Developers can anticipate the structure of the endpoints, which leads to fewer errors and a more efficient integration process. It also enhances the readability and maintainability of your code.

What are the benefits of using nouns instead of verbs in naming REST API endpoints?

In REST, we conceptualize our data as resources. Using nouns to name endpoints aligns with this concept as it makes clear what resource the endpoint is exposing. Verbs, on the other hand, are better suited for defining actions, which in RESTful design, are represented by HTTP methods like GET, POST, PUT, and DELETE.

Why should we use plural nouns in REST API endpoint naming?

Using plural nouns is a common convention in REST API design. It helps ensure consistency and better reflects the possibility of the endpoint returning multiple resources. For example, /users could represent one user or many, while /user might imply it only represents a single user.

Can you explain the role of HTTP methods in REST API endpoints?

HTTP methods represent actions on the resources. The most common are GET (retrieve), POST (create), PUT (update), and DELETE (remove). By using these methods, we can simplify our endpoint names, focusing them solely on the resources.

Why should deep nesting be avoided when naming REST API endpoints?

Deeply nested endpoints can become complex and difficult to manage, leading to potential confusion and mistakes. It's generally recommended to limit nesting to one level, i.e., /users/123/posts, instead of deeper nesting like /users/123/posts/456/comments.

How does proper REST API endpoint naming enhance troubleshooting?

Well-named endpoints make it easier to locate and correct problems. If the endpoint's name reflects its function, developers can identify issues more quickly, enhancing productivity and reducing downtime.

How can proper endpoint naming facilitate the growth and scalability of my application?

As your application grows and the number of your API endpoints increases, a robust naming convention helps manage this growth effectively. Consistent and clear endpoint names ensure that new endpoints integrate smoothly with existing ones, thus facilitating scalability.

Blog

Best Practices for Naming REST API Endpoints

by Terence Bennett

May 12, 2026

Last updated: May 2026

REST API endpoint naming is the practice of choosing consistent, resource-oriented URLs for every operation in your API. Good naming makes an API predictable, easier to integrate, and — increasingly — easier for AI agents to use safely. Bad naming makes every endpoint a question mark, slows integration, and produces bugs. This guide covers the conventions used by the best public APIs (Stripe, GitHub, Twilio), the common mistakes that hurt API quality, and how AI consumption via the Model Context Protocol changes what good naming looks like in 2026.

Quick summary

Use nouns, not verbs: POST /orders, not /createOrder.
Pluralise collections: /customers for the collection, /customers/123 for a single item.
Use lowercase + hyphens: /order-items, not /OrderItems or /order_items.
Limit nesting: at most one level deep — /customers/123/orders, not /customers/123/orders/456/items.
Version explicitly: /v1/customers in the path, or via the Accept header.
Plan for AI consumption: clear names + good OpenAPI descriptions = correct LLM tool selection via MCP.

Why naming matters for REST API endpoints

An API is a contract. The URL of every endpoint is part of that contract — and unlike most other parts of an API design, it's the most public, the most often-cited, and the hardest to change later. Backwards-incompatible URL changes break every consumer. Consistent, predictable naming therefore pays compounding interest.

Good naming has three direct effects:

Faster integration: Developers can guess unfamiliar endpoints based on conventions they've already learned. GET /customers/123/orders needs no documentation if the rest of the API uses the same shape.
Lower support burden: Consistent URLs mean fewer "how do I…" tickets, less duplicated documentation, and easier onboarding for new developers.
Safer LLM tool use: AI agents discovering your API via the Model Context Protocol read endpoint names and descriptions to decide which tool to call. Predictable naming reduces the chance of an agent picking the wrong endpoint.

What is a REST API endpoint?

A REST API endpoint is the combination of a URL and an HTTP method that, together, identify a single operation in your API. GET /customers/123 is one endpoint; DELETE /customers/123 is a different endpoint, even though the URL is identical. The URL identifies the resource; the HTTP method identifies the action.

Three terms get confused in this area:

URI (Uniform Resource Identifier): the full address of the resource — https://api.example.com/v1/customers/123.
Path: the part after the host — /v1/customers/123. This is what most "endpoint" discussions focus on.
Endpoint: path plus HTTP method — GET /v1/customers/123. This is the actual operation.

For more on the underlying architecture, see REST APIs: an overview of basic principles.

REST API endpoint naming best practices

The following conventions show up across virtually every well-regarded public API. They aren't laws — but if you deviate from them, deviate deliberately, and document why.

Use nouns to describe resources. The URL identifies what you're acting on; the HTTP method describes the action. Use POST /orders, not /createOrder; GET /customers/123, not /getCustomerById?id=123.
Use plural nouns for collections. /customers, not /customer. The same path with an ID points to a single item: /customers/123. Plural-only is the dominant convention in modern APIs and keeps URL grammar consistent.
Use lowercase letters and hyphens. /order-items, not /OrderItems or /order_items. URLs are case-sensitive in the HTTP spec but case-insensitive in many real-world stacks — sticking to lowercase prevents inconsistency. Hyphens are easier to read than underscores in browser URL bars.
Maintain hierarchical structure. Use the path to express containment relationships — /customers/123/orders for the orders belonging to customer 123. This makes URLs self-documenting.
Limit nesting depth. One level of nesting is normal; two levels is a smell; three levels is almost always wrong. /customers/123/orders/456/items/789/notes couples your URL structure to your data model and breaks every time relationships change. Link deeper resources from their own top-level paths.
Avoid file extensions. Don't end paths with .json or .xml. Use the Accept header or a query parameter to negotiate format. The URL identifies the resource; the format is a presentation concern.
Avoid special characters. Stick to letters, numbers, and hyphens. Reserved characters like ?, &, =, % have specific meanings in URLs. Spaces and Unicode characters cause encoding problems.
Be explicit about versioning. Use /v1/customers in the path, or Accept: application/vnd.example.v1+json in headers. Pick one and stick with it. Never have an unversioned API and a versioned API serving different responses.
Use query parameters for filters and pagination. Path identifies the resource; query string filters or paginates: /orders?status=paid&page=2. Don't put filters in the path.
Be consistent across the entire API. If you pluralise /customers, also pluralise /orders, /products, /payments. Mixing conventions within the same API is worse than picking the "wrong" one consistently.

Good vs bad endpoint naming — cheat sheet

Concrete examples of the same operations done well and done badly. The "Bad" column is drawn from real APIs in the wild.

Operation	Good	Bad	Why
List customers	`GET /customers`	`GET /getAllCustomers`	HTTP method is the verb; URL is the resource
Get one customer	`GET /customers/123`	`GET /customer?id=123`	Use path segments for IDs, query for filters
Create customer	`POST /customers`	`POST /createCustomer`	HTTP verb already says "create"
Update customer	`PATCH /customers/123`	`POST /updateCustomer?id=123`	PATCH is the partial-update verb
Delete customer	`DELETE /customers/123`	`POST /deleteCustomer?id=123`	DELETE has clear intent + supports caching invalidation
List a customer's orders	`GET /customers/123/orders`	`GET /orders/byCustomer?customerId=123`	Hierarchical path expresses ownership
Filter and paginate	`GET /orders?status=paid&page=2`	`GET /paidOrdersPage2`	Query string is the right tool for filters/pagination
Versioned endpoint	`GET /v1/customers`	`GET /customers_new`	Explicit versioning beats version-by-suffix
Action on a resource	`POST /orders/123/refund`	`POST /refundOrder?id=123`	Sub-action is acceptable when the verb doesn't fit CRUD; still use a noun

Common mistakes to avoid

Beyond the positive practices, these are the recurring naming mistakes that hurt API quality:

Non-descriptive endpoint names: /data, /info, /process. Names that don't describe the resource force every consumer to read documentation to understand what an endpoint returns.
Mixed case styles: Using /orderItems in one place, /order-items in another, and /order_items in a third. Pick one and stick with it across the whole API.
Verbs in URLs: /getOrder, /saveCustomer, /updateProfile. The HTTP method already conveys the verb.
Unversioned APIs that change: An API without a version is an API that can't evolve without breaking consumers. Add a version from day one, even if the first version is the only one for a long time.
Putting metadata in URLs: /customers/v2_active_premium tries to encode multiple dimensions in a single path segment. Use query parameters or separate endpoints.
Inconsistent error handling: Naming aside, the response shape for errors should be identical across every endpoint. Inconsistent errors are nearly as bad as inconsistent URLs.

Naming endpoints for AI agents and the Model Context Protocol

The biggest shift to API design in the last two years isn't a new framework — it's who's calling the API. AI agents built on large language models now make a growing share of API calls, fetching data, invoking tools, and chaining requests across services on behalf of users.

This creates a new layer in the stack. The Model Context Protocol (MCP), introduced by Anthropic and rapidly adopted by other LLM providers, is the emerging standard for how AI models discover and call APIs at runtime. An MCP server exposes API endpoints as tools the model can read and invoke; an MCP client (like Claude or ChatGPT) consumes those tools.

That changes a few things for endpoint naming specifically:

The endpoint name is part of the tool-selection prompt. When an LLM is choosing which tool to call, it reads endpoint names and descriptions from the OpenAPI spec. Vague or abbreviated names ("/proc", "/q1") get skipped in favour of clearer alternatives. Descriptive resource names win.
Each endpoint needs a one-sentence semantic description. The OpenAPI description field is no longer optional metadata — it's the primary signal an LLM uses to understand what an endpoint does. Write it for an intelligent reader who's never seen the API.
Granular auth and scopes become essential. You don't want an LLM to delete production records or access another tenant's data. Per-endpoint scopes let you give an agent exactly the access its task requires.
Data access needs governance, not just authentication. Which fields can an agent read? Which cells should be redacted? Which queries should be logged for audit?

The piece of infrastructure handling that data-access layer is the AI Data Gateway — a secure intermediary between enterprise data sources and AI systems. Where a traditional API gateway handles authentication, rate limiting, and routing for human-driven traffic, an AI Data Gateway adds AI-aware controls: identity passthrough, deterministic query enforcement, prompt logging, content filtering, and field-level data governance for agent traffic.

For teams already running an API gateway, an AI Data Gateway sits as a complementary layer — purpose-built for the specific risks and traffic patterns of AI consumption. See What is an AI Data Gateway for the full architecture, and Zero Trust for LLMs for how the security model works in practice.

Benefits of consistent REST API endpoint naming

The compound effect of getting endpoint naming right shows up in five places:

Faster integration: Developers can guess unfamiliar endpoints from the patterns they've already learned. New consumers integrate in minutes, not days.
Lower documentation burden: Clear names reduce the amount of explanation needed in API docs. The URL itself tells most of the story.
Easier troubleshooting: When endpoint names match the data model, log lines and error messages are interpretable at a glance. Engineers can navigate from a log entry to the relevant code without context.
Better caching: Standard HTTP methods + clean URLs let CDNs and gateways cache responses correctly. API caching is dramatically easier with a well-named API.
Cleaner authorisation model: Resource-oriented URLs naturally line up with role-based access control. API key scopes and OAuth 2.0 scopes can target paths instead of rules in code.
Safer LLM consumption: AI agents pick the right tool more often when names are clear and consistent.

How DreamFactory fits in

DreamFactory's foundational capability is instant REST API generation: connect a database (Oracle, SQL Server, PostgreSQL, MySQL, Snowflake, Databricks, MongoDB — 40+ supported), and the platform auto-generates a fully documented, role-protected REST API in minutes, with no code written. The platform has been doing exactly this for over a decade. Authentication (Microsoft Entra ID, OAuth 2.0, OpenID Connect, SAML 2.0, LDAP, Active Directory, API keys), role-based access control (per table, endpoint, and HTTP verb), rate limiting (per user, role, or service), audit logging (every call captured with calling user, timestamp, and payload), and OpenAPI documentation are built in. Server-side scripting in PHP, Python, or Node.js handles custom business logic.

The AI Data Gateway is the newer chapter — a built-in MCP server that exposes the same auto-generated REST API to AI agents (Claude Desktop, Claude Code, ChatGPT, Cursor, Windsurf). The company's framing: "turn your database into an auditable, governed API layer for AI." The core principle is data stays put — keep your systems of record intact, generate a governed API on top, and let AI agents query through that layer rather than receiving raw data extracts. In DreamFactory's MCP tutorial, CTO Kevin McGahey demonstrates the full flow: database credentials, one MCP call, auto-generated API, read-only role, API key — and Claude Code building a working dashboard in minutes.

DreamFactory deploys via Linux installer (Ubuntu, Debian, CentOS, RHEL, Fedora), Windows (IIS or Apache), Docker, Kubernetes via official Helm chart, or NPX quick install. Air-gapped deployment is fully supported — as used by the Vermont Agency of Transportation to expose an Oracle database and a 1970s-era IBM S370 mainframe through a unified API layer.

DreamFactory's customers include ExxonMobil, Toyota, Saint-Gobain, PPG, Deloitte, Google Cloud, AkerBP, Netgear, Miller Industries, the National Institutes of Health, the Vermont Agency of Transportation, D.A. Davidson, and Pillsbury Law — spanning energy, automotive, industrial, finance, government, healthcare, and legal. G2 rates the product 4.7 with badges for "Easiest to Use," "Fastest Implementation," and "Best ROI." See the DreamFactory AI page or request a demo.

Frequently asked questions

Why is a consistent naming convention crucial for REST API endpoints?

Consistent naming makes an API predictable, easier to learn, and easier to maintain. Developers (and increasingly, AI agents) rely on patterns to guess what an endpoint does without reading documentation. Inconsistent naming forces every consumer to look up every endpoint, which slows integration, increases support burden, and produces bugs.

Why use nouns instead of verbs in REST API endpoint names?

REST is built around the idea that endpoints describe resources (nouns), and HTTP methods describe actions (verbs). Use POST /orders instead of /createOrder; DELETE /orders/123 instead of /deleteOrder?id=123. The HTTP method already conveys the action, so duplicating it in the URL is noise.

Should REST API endpoints use plural or singular nouns?

Use plural nouns for collections. /customers, not /customer. The same path with an ID points to a single item: /customers/123. Plural-only is the dominant convention in modern API design — Stripe, GitHub, Twilio all follow it — and it keeps the URL grammar consistent across collection and single-item operations.

What's the role of HTTP methods in REST API endpoint design?

HTTP methods carry the verb. GET reads, POST creates, PUT replaces, PATCH partially updates, DELETE removes. Combined with resource-oriented URLs, they let you express the entire CRUD vocabulary without ever putting a verb in the URL. See our guide to idempotency for which methods are safe to retry.

Why should I avoid deep nesting in REST API endpoints?

Deep nesting (/customers/123/orders/456/items/789/notes) couples your URL structure to your data model and makes endpoints fragile when relationships change. As a rule, nest one level deep at most (/customers/123/orders) and link to deeper resources via their own top-level paths.

How should I version REST API endpoints?

The two common patterns are URL path versioning (/v1/customers) and header-based versioning (Accept: application/vnd.example.v1+json). URL versioning is simpler and easier to debug; header versioning keeps URLs cleaner. Pick one and stick with it. Always treat the version as a contract and avoid breaking changes within a version.

How should I name REST API endpoints for AI agents using MCP?

When AI agents discover and call your API via the Model Context Protocol (MCP), the endpoint name and description become the input to the model's tool-selection decision. Use clear, descriptive resource names; pair each endpoint with a one-sentence semantic description in your OpenAPI spec; avoid abbreviations the model won't recognise; and keep the auth and scope boundaries fine-grained so an agent can be given exactly the access it needs.

Should REST API endpoints use hyphens or underscores?

Use hyphens. /order-items reads more naturally and is the convention across most major public APIs. Underscores are harder to read in URLs (the underscore can be hidden by the link underline) and aren't compatible with some legacy tooling. Never use camelCase in paths — URLs are case-sensitive in spec but case-insensitive in many real-world deployments, which causes inconsistency.

How does proper naming enhance API maintainability?

Predictable names mean new team members can guess endpoints correctly, AI agents can self-discover available operations, monitoring and logging tools can pattern-match URL structures, and refactoring is safer because the impact of a name change is local. Cumulatively, consistent naming reduces both the cognitive load on humans and the error rate of LLM-driven integrations.