1. Overview
Endpoints are an important concept in API design. Understanding endpoints and their working is essential in creating or consuming APIs.
In this article, we’ll understand endpoints and discuss their role in API design and development. Also, we’ll examine different protocols and HTTP methods for endpoints and the distinction between endpoints and URIs.
2. What Are Endpoints?
An endpoint in the context of an API (Application Programming Interface) is a specific URL linking to a particular resource. When interacting with an API, endpoints can execute specific activities like requesting data or triggering a process.
Consider an API for user management containing the following endpoints:
In this diagram above, all the requests having the same base URL go to the same server. For example, https://myserver1.com requests go to “Web Server 1,” and https://myserver2.com requests go to “Web Server 2“. The webserver takes different actions based on the API endpoint. We use the /users endpoint to manage the collection of users as a whole and /users/{id} endpoint to manage individual users.
Endpoints are an important concept in API design and are used to define the various resources and actions that can be performed through an API.
2.1. Endpoints with Multiple Protocols
An endpoint is essentially a combination of a URL and an HTTP method. The HTTP method defines the type of operation supported by that endpoint. An endpoint can therefore support multiple protocols by allowing different HTTP methods.
For instance, consider an endpoint /users representing a collection of users in an API. This endpoint could support the following protocols:
- HTTP GET: Retrieves all the users from the collection using the HTTP GET technique
- HTTP POST: We can add a new user to the collection using the HTTP POST technique
- HTTP PUT: Update the full collection of users using the HTTP PUT technique (i.e., replacing it with a new collection)
- HTTP DELETE: Delete one or more users from the collection using the HTTP DELETE technique
Here, the same endpoint (/users) supports multiple protocols (GET, POST, PUT, DELETE) by allowing different HTTP methods. As a result, the API may offer a variety of functions for controlling the group of users from a single endpoint.
3. Endpoints vs. URI
A URI (Uniform Resource Identifier) is a string of characters that identifies a name or a resource. In contrast, an endpoint is a single URL representing a specific API resource or activity.
APIs use endpoints to specify the different resources and operations that may be carried out through the API. An endpoint often represents a resource or activity using a specific URL and an HTTP method (such as GET, POST, PUT, or DELETE).
On the other hand, a URI is a broader concept that can identify any type of resource, not just those exposed through an API. A URI can be a URL (Uniform Resource Locator), which specifies the location of a resource on the internet, or a URN (Uniform Resource Name), which identifies a resource by name rather than by location.
In summary, an endpoint is a specific URL representing a specific API resource or action. At the same time, a URI is a broader concept that can identify any resource type.
4. Conclusion
In this article, we learned about endpoints and their role in API design and development. Endpoints are URLs that represent specific resources or actions in an API. We can bind endpoints to different protocols and HTTP methods. We also compared endpoints with URIs and highlighted the differences between these two concepts.