API endpoint, explained
In a REST API, an endpoint is the pairing of a method and a path, such as GET /v1/invoices/{id} or POST /v1/invoices. The same path with a different method is a different operation. A full request URL combines the base URL, the path, path parameters and query parameters: https://api.example.com/v1/invoices?status=open.
Each endpoint has its own contract: accepted parameters and headers, the request body schema, response shapes, status codes, authentication and rate limits. In an OpenAPI document, endpoints appear as paths and operations, each with an operationId.
GraphQL usually exposes a single endpoint such as POST /graphql with operations chosen in the query, while gRPC exposes methods on services rather than URL paths.
Endpoints are the most visible part of an API surface, so removing or renaming one is the most obvious kind of breaking change. Subtler changes to an endpoint, such as a new required parameter, a different default or a narrower response, break clients just as reliably.
Related terms
- REST API: A REST API is an HTTP API organised around resources identified by URLs and manipulated with standard methods such as GET, POST, PUT, PATCH and DELETE.
- HTTP status codes: HTTP status codes are three-digit numbers a server returns with each response to signal its outcome, grouped in five classes from 1xx to 5xx.
- OpenAPI Specification: The OpenAPI Specification is a standard, language-agnostic format (YAML or JSON) for describing HTTP APIs: their paths, operations, parameters, schemas and authentication.
- API: An API (application programming interface) is a defined contract that lets one piece of software request data or actions from another without knowing how it is implemented.