12

I am new to the web world and I just read the difference between a route and an endpoint.

I know the definition of an API. But what is the difference between an API and routes (endpoints)?

It seems to me, when somebody says "build an API" or according to the YouTube tutorials that I have watched, they simply build a route using web frameworks like Express.js or Flask like '/hello', which returns "hello".

If that is an API, are an API and a route interchangeable? Like, if I have, for example, 3 routes: '/hello', '/users', '/users/<userId>'. Can I say I have 3 APIs?

nbro
  • 15,395
  • 32
  • 113
  • 196
pizza
  • 584
  • 1
  • 10
  • 19

3 Answers3

8

In short to my mind:

  • API is about working with data using JSON or XML (as a rule) for input/output data (CRUD operations without any UI). API should follow some rules and structure. Ex.: GET /{entity_type}/{entity_id} means that this method will try to get entity with passed type and id
  • endpoint may be an API (they often are spelled together like "API endpoint") but at the same time it may be just an URL that leads somewhere without explicit manipulation with any data, for instance, trigger/webhook/gateway etc.
  • route is a path to some website/page/controller with a meaningful name to interact with the user. Route receives some user input (handles user actions) and represents some results in a convenient way (for example, render markup).
Slava
  • 878
  • 5
  • 8
  • Thank you! Then if I have, for example, ```GET /{entity_type}/{entity_id}```, ```POST /{something}/{something}```, and ```GET /{user}/{userId} ```, does it mean I have 3 APIs? – pizza Jul 17 '20 at 17:52
  • 7
    I would say you have one API with 3 endpoints) API is something like a set of methods that cover some functionalty. It's an entire application that provides some fucntionality through list of methods (endpoints). For example, YouTube API allows you to get list of videos, get list of comments under the video, remove particular video etc. But all these actions are provided by one API – Slava Jul 19 '20 at 13:50
4

TL;DR

API, an endpoint and a route are interchangeable but a subtle difference exist.

Long Read

API as in web API world are represented by URI or REST endpoints. Best to understand it from programming analogy. Take Java API specification, there are methods aggregated in classes and packages. You may think a class as API but you actually call its methods.

Similarly, "/users" can be called a "users" API. This is also an endpoint. You need to read its specification to understand its usage. This API can have further related REST endpoints. For example - "/users/{id}" or "/users/admin/". All those have their own specification. Collectively, it becomes part of one API documentation.

API is usually a definition term, Endpoint or route are physical representation. When somebody says "build an API" that means you have to define its specification e.g. protocol, request/response schema, (may be) security credentials and (of course) an endpoint to hit.

Nitin Gaur
  • 922
  • 1
  • 14
  • 21
0

An API is the part of your app that is directly accessed by agents outside your app. But what is your app?

An application (app) can be subdivided into any number of subdivisions using any criteria imaginable, and each may be considered an app unto itself.

For example, I might decide that my app is the combination of both program running on a server, and a user interface program running on his machine, and that the internet communication between both is also part of my app. The API of such app is the client's interface the human or robot uses.

Or, I could say I have 2 separate apps, one is the server app, one is the client app, and the internet communication is not part of either. Besides the client's API now I also have the server API which receives requests from the client.

Then I could say my server actually consists of 4 apps, each of which handles a different sub-service. Each of them will have an API to communicate with each other.

Ultimately, I could even consider each individual function to be a separate app. The API of a function is how it's called (its name and arguments, in the correct format). You may consider the return format as well (or not).

In your example you mention 3 routes. If you consider each service they target as a separate app, they yes, you have 3 APIs. If you are thinking about it as a single whole, you have 1 API. It all depends on what you consider to be "the app", the API is referring to.

Juan Perez
  • 212
  • 2
  • 10