API Endpoint
A specific URL in an API where a resource can be accessed or an action can be triggered.
Detailed Explanation
Endpoints are the touchpoints where your frontend interacts with the backend. A well-designed endpoint like `/api/v1/users/123` is self-descriptive. Managing endpoints involves handling authentication, rate limiting, and versioning to ensure that updates don't break existing client applications.
Quick Summary
An API endpoint is the URL plus HTTP method that addresses one operation on an API, GET /v1/users/42, POST /v1/orders. Good endpoints are predictable, versioned, authenticated, and rate-limited.
Key Takeaways
- An endpoint = path + method; the same path with different methods is a different endpoint.
- Versioning (in the path /v1/, in a header, or via content negotiation) is essential, once a client depends on you, breaking changes need a new version.
- Authentication, rate limiting, and observability are cross-cutting concerns that apply to every endpoint, usually via middleware.
- Plural nouns and predictable nesting (/users/{id}/orders) make endpoints discoverable without docs.
- Endpoints should return appropriate HTTP status codes so generic clients and monitoring tools work without endpoint-specific logic.
When to use it
- Frontend SPAs that call a backend over /api/* routes.
- Mobile apps integrating with a server-side API.
- Third-party integrations consuming a public REST or GraphQL service.
- Internal service-to-service communication in a microservices architecture.
Common Mistakes
- Burying actions in query strings (/api?action=deleteUser&id=42) instead of using paths and verbs.
- Skipping versioning until you need a breaking change, then having to choose between breaking clients or freezing the API forever.
- Returning HTML error pages from JSON endpoints, clients parsing JSON crash on the unexpected payload.
- Forgetting to rate-limit public endpoints, which leaves the service vulnerable to scraping and abuse.
API Endpoint, Frequently Asked
What's the difference between an endpoint and an API?
An API is the whole contract, every endpoint a service exposes plus the rules for using them. An endpoint is a single addressable operation within that API.
Should endpoints use singular or plural nouns?
Plural is conventional (/users/42 rather than /user/42) because it keeps collection and item endpoints symmetric: GET /users returns a list, GET /users/42 returns one.
How should I version API endpoints?
Path-based versioning (/v1/, /v2/) is the simplest and most cache-friendly. Header-based versioning (Accept: application/vnd.api.v2+json) keeps URLs stable but is harder to debug. Pick one and use it consistently from day one.