CODEWITHSUNDEEP
restendpoint
David
David

Reputation: 398

What is a REST API entry point and how is it different from an endpoint?

What is a REST API entry point and how is it different from an endpoint?

I have searched for various definitions online but still can't seem to wrap my head around them (I am new to APIs in general). From what I understand, they provide means of communicating with the server but what are they exactly and how are entry points and endpoints similar or different?

Upvotes: 23

Views: 27117

Answers (3)

Byebye
Byebye

Reputation: 1103

I think it's relevant to add "perspective" to the definition.

Any end-point of communication can be said to also be an entry-point. Let me elaborate.

Most forms of communication that we utilize today can be captured by a graph consisting of 2 vertices and 1 edge which is incident to those 2 vertices.

I.e. applications A and B communicate and we model this as an undirected graph G:

  • A - B

Or any of the following directed graphs:

  • A -> B
  • A <- B
  • A <-> B

Example

Let's take A -> B as an example. Here we communicate from A to B.

Suppose B has defined a a location L it controls and defined to be open to communication.

Now A sends a communication-payload to location L.

Sender's perspective

From the perspective of A the recipient B is an "end-point". In the sense that there is no further control of the communication-payload once sent to B.

Recipient's perspective

From the perspective of B however, the location L is an entry-point. In the sense this is where B has an opening, a place where it allows entry.

Communication-channel's perspective

The final perspective is that of the communication-channel, i.e. the edge that connects A and B. Here, both A and B can be considered to be end-points of communication or rather, delivery-points. Since a communication-payload is delivered through the communication-channel to either A or B.

However, you could say that, as with the above statements, the communication-channel is also an entry-point, as it is where a communication-payload enters to be delivered.

So which is it?

In the case of Representational State Transfer (REST), I'd wager the usage of an "endpoint" is an inheritance of RFC 9293 specification which describes the TCP protocol. Since TCP underlies HTTP, and HTTP underlies REST I'd say this is where the term came from.

Note however that the RFC 9112 specification for HTTP only uses the term "endpoint" once and it does so in the context of a "server endpoint". In other words, this is an endpoint from the perspective of a client communicating to a server.

As for REST, it has no "official" specification. The term "REST" was coined by Roy Thomas Fielding in his PhD. dissertation and it does not mention entry-points nor endpoints.

Another point worth making is that the entrypoints mentioned in the other answers are actually the "base"-url/path of the API and the OpenAPI specification specifically mentions these as part of the Server Object definition.

TL:DR;

It seems that the "endpoint" and "entry-point" terminology in REST is based largely on common usage/phrasing or more likely, inheritance from specifications on top of which REST is build. As such, the terms are not clearly defined terms as proposed in the other answers.

Upvotes: 3

tiomno
tiomno

Reputation: 2228

Agree with Roman Vottner here and gave a thumb up. I only want to add a few more links here for anyone trying to get a clear idea.

API Endpoint

I like the answer here: https://smartbear.com/learn/performance-monitoring/api-endpoints/

Simply put, an endpoint is one end of a communication channel. When an API interacts with another system, the touchpoints of this communication are considered endpoints. For APIs, an endpoint can include a URL of a server or service. Each endpoint is the location from which APIs can access the resources they need to carry out their function.

And samples here: What is an Endpoint?

https://example.com/api/login
https://example.com/api/accounts
https://example.com/api/cart/items

API Entry Point

Look here: https://restful-api-design.readthedocs.io/en/latest/urls.html

A RESTful API needs to have one and exactly one entry point. The URL of the entry point needs to be communicated to API clients so that they can find the API. Technically speaking, the entry point can be seen as a singleton resource that exists outside any collection.

So, following the previous example, it would be:

https://example.com/api

Extra note: in GraphQL world, there is a single endpoint for the API, no entry point (https://graphql.org/learn/best-practices/#http). Usually in the form

https://example.com/graphql

Upvotes: 29

Roman Vottner
Roman Vottner

Reputation: 12829

Simply speaking an entry point might be something like http://api.your-company.com which a client will enter without any a-priori knowledge. The API will teach the client everything it needs to know in order to make informed choices on what things it could do next.

Regarding Endpoints Wikipedia i.e. state the following:

Endpoint, the entry point to a service, a process, or a queue or topic destination in service-oriented architecture

In a broad sense, the endpoint is just the target host invoked that should process your request (or delegate to some other machines in case of load balancing and what not). In a more narrow sense an endpoint is just the server-sided stuff invoked that is processing your request, i.e. a URI like http://api.your-company.com/users/12345 will ask for a users representation (assuming a GET request). The concrete user is the resource processed while the endpoint might be actually a Spring (or framework of your choice) based service handling all requests targeting everything http://api.your-company.com/users/* related.

Upvotes: 10

Related Questions