What is an API Endpoint? Definition, Examples, Best Practices

What is an API endpoint?

An API endpoint is the address a client calls to use one specific operation of an API: a URL path combined with an HTTP method, such as GET /users/42 to read a user or POST /users to create one. The same path with a different method is a different endpoint. Together, all endpoints make up the surface of the API.

REST APIs expose many endpoints, usually one per resource and operation. GraphQL typically exposes a single endpoint (often /graphql) and lets the client describe the data it wants in the request body. gRPC names its operations as methods of a service instead of URL paths.

How an API endpoint works

A REST endpoint has three parts:

• Base URL. Protocol, host and optional prefix, for example https://api.example.com.
• Path. The route to a resource, for example /users/42. Query strings such as ?page=2&limit=20 refine it.
• HTTP method. The verb that selects the operation: GET, POST, PUT, PATCH or DELETE.

Here is a complete call to a "create user" endpoint and the answer it returns:

POST https://api.example.com/users
Content-Type: application/json
Authorization: Bearer <token>

{ "name": "Alice", "email": "alice@example.com" }

HTTP/1.1 201 Created
Location: /users/43

The method matters beyond naming. Per MDN, only GET is safe (it changes nothing on the server), and GET, PUT and DELETE are idempotent, meaning repeating the request has the same effect as sending it once. POST and PATCH are not idempotent, which is why retries on them need care: see idempotency.

Common endpoint patterns

Design conventions that hold up

• Nouns in paths, verbs in methods. /users, not /getUsers.
• One naming style. Plural or singular, kebab-case or snake_case: pick one and use it everywhere.
• Paths that show relationships. /users/42/orders reads as "the orders of user 42".
• Real status codes. 201 after a create, 204 for an empty success, 400 for a bad request, 401 when the caller is not authenticated, 403 when it is not allowed, 404 when nothing is there, 429 when it sent too many requests, 5xx for server faults (MDN, based on RFC 9110).
• Pagination and filters in the query string. /users?role=admin&page=2.
• Explicit versions. /v1/users lets you ship breaking changes as /v2.
• A machine-readable spec. Describe every endpoint in OpenAPI, as covered in What is Swagger.

Common endpoint mistakes

• Actions in the path. POST /createUser and ?action=delete work against the method semantics. Use POST /users and DELETE /users/42.
• HTTP 200 with an error in the body. Clients, caches and monitors read the status code first. Return 4xx or 5xx for failures.
• Secrets in the URL. Tokens and personal data in paths or query strings end up in logs, browser history and referrers. Send them in headers or the body.
• Inconsistent error format. If one endpoint returns {"error": ...} and another {"message": ...}, every client needs special cases.
• No authorization check per endpoint. Authentication says who the caller is. Each endpoint still has to check what that caller may do.
• No rate limit. An unbounded endpoint is the first to fall over under abuse or a retry storm. Answer with 429 and a Retry-After header. Background: API rate limiting causes.

Testing and monitoring API endpoints

Each endpoint is a unit you can verify at several levels. API testing checks that it returns the right data and status. Load testing shows how it behaves when many clients call it at once; LoadFocus runs JMeter and k6 tests from 25 cloud regions, and the free plan includes up to 10 virtual users. Once the endpoint is live, API monitoring calls it on a schedule and checks status code, body, headers and response time, so a 200 with the wrong payload still fails; the free plan checks every 5 minutes. For a one-off look at a public URL, the API status checker sends a request from six regions with no signup. For typical slow-endpoint causes, read common API performance issues and how to detect them, and for the monitoring side see What is API monitoring.

FAQ: API endpoints

What is the difference between an API and an API endpoint?

The API is the whole interface: every endpoint plus its schemas, authentication and error formats. An endpoint is one operation inside it, such as the create-charge call in a payment API.

Are GET /users and POST /users the same endpoint?

No. They share a path but use different methods, so they are two endpoints: one lists users, the other creates one.

Is an endpoint the same as a URL?

Not quite. The URL is only the address. The endpoint is the URL plus the HTTP method, because the method decides what the server does.

How many endpoints should an API have?

As many as its scope needs. A small focused API may have a handful, a large platform API hundreds. The count says nothing about quality; consistency and good documentation do.

How do REST and GraphQL endpoints differ?

REST spreads operations over many endpoints, one per resource and method. GraphQL usually has one endpoint, and the query in the request says which fields to return.

How do I change an endpoint without breaking clients?

Add a version to the path (/v1/users, /v2/users), run both during a transition, announce a retirement date for the old one and document what changed.