Endpoint
A specific addressable interface location where a client can interact with a software service using defined operations and messages.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/endpoint/
01What it means
An endpoint is a concrete point of interaction exposed by an API or network service. In an HTTP API it is commonly described by a server address, path, and supported method, such as GET /orders/{id}; the path alone does not fully define the operation.[1][2]
- ClientMethod, address, parameters, content
- Endpoint contractRoute + operation + security + responses
- ImplementationAuthorize, execute, observe
Registered status, headers, result, or structured error
A path alone is incomplete; inputs, outputs, errors, security, constraints, observability, versioning, and deprecation complete the endpoint definition.
02Why it matters
Endpoints turn an API contract into callable capabilities. Clear boundaries and consistent naming help consumers discover operations, apply authorization correctly, diagnose failures, and understand which behavior can change independently.
03When to use it
Use the term when identifying where and how a client invokes a specific service operation. Use resource, route, URL, or server when that narrower concept is what matters; they are related but not interchangeable with endpoint.
04How it works
- Choose the capability or resource that the service will expose.
- Assign an address and the protocol operation or method accepted at that address.
- Define parameters, request content, responses, errors, security, and usage constraints.
- Route matching client requests to the implementation responsible for the operation.
- Document, test, observe, version, and eventually deprecate the endpoint as part of the API contract.
05A practical example
An inventory service exposes GET /products/{sku}/availability. The same path with PUT would be a different operation, so documentation specifies the method, identifier format, authorization, response schema, error codes, and rate limits together.
06Where it breaks
The word is used loosely across HTTP, messaging, and networking, so an endpoint name alone may not identify the protocol or operation. Too many narrowly scoped endpoints can produce chatty integrations, while broad endpoints may mix unrelated responsibilities.
Common mistakes
- Treating a path by itself as a complete endpoint while ignoring the HTTP method and server context.
- Using endpoint, API, server, and URL as interchangeable terms.
- Designing endpoints around database tables without considering consumer workflows.
- Changing endpoint behavior while leaving its documented contract unchanged.
07Sources
- OpenAPI Specification: Paths ObjectOpenAPI Initiative · Technical specificationOpenAPI Specification: Paths Object
- APIMDN Web Docs · Official technical documentationAPI