Endpoints vs Routes: What every API hacker needs to know

I recently had an interesting conversation on Twitter/X that got me thinking about API endpoints vs routes. It all started with this tweet:

The conversation progressed into whether this was one vulnerability or two. It also started questioning my understanding and definition of what an API endpoint vs. an API route means.

I’ve decided to clarify my thinking by writing this post. I want to explore the nomenclatures and see what the community thinks. By the end of the article, I am hoping you agree with me that Manuel should be submitting two separate reports to the vendor.

What is an API endpoint?

An API endpoint is a specific URL or URI (Uniform Resource Identifier) where an API can be accessed by a client application. It represents a specific function or resource available in the API. The endpoint is what the API exposes for a specific operation. It is the point of interaction where the API services can be consumed.

Consider an API for a user management system. An endpoint in this API might be https://api.example.com/users/12345, where accessing this URL could return information about the user with ID 12345.

What is an API route?

An API route is the definition of paths and methods (like GET, POST, PUT, DELETE) in an API. It’s a broader concept that includes the path, the method, and often the logic that gets executed when that path and method are used.

Routes are used to define how an application will respond to client requests to a particular endpoint, often including paths with variable parts (like user IDs) and defining the logic that should be executed when the route is hit.

In the same user management system, a route might be defined as GET /users/:userId, where :userId is a variable part of the path, and GET is the method. This route defines how the application will handle GET requests for any user ID.

Confused? Let’s look at an example.

Let’s use some simple pseudo-code here to walk through this. Consider this code:

const express = require('express'); 
const bodyParser = require('body-parser'); 
const app = express();
const port = 8000;

app.use(bodyParser.urlencoded({ extended: false }));
app.use(bodyParser.json()); 

let users = [
	{ id: 1, name: 'alice' },
	{ id: 2, name: 'bob' },
	{ id: 3, name: 'chuck' }
];

app.get( '/users', (req, res) => {
	res.json( users );
});  

app.get('/users/:userId', (req, res) => {
    const user = users.find(u => u.id === parseInt(req.params.userId));

    if (!user) {
        return res.status(404).send();
    }

    res.status(200).json(user);
});  

app.put('/users/:userId', (req, res) => {
    const index = users.findIndex(user => user.id === parseInt(req.params.userId));

    if (index === -1) {
        return res.status(404).send();
    }

    const { name } = req.body;
    if (!name) {
        return res.status(400).send({
            success: 'false',
            message: 'name is required',
        });
    }

    users[index].name = name;
    res.status(201).json(users[index]);
});  
  
app.listen(port, err => {
    if (err) {
        console.error("Error while starting server:", err);
    } else {
        console.log(`Server has been started at ${port}`);
    }
});

This is basic scaffolding for an API in NodeJS + Express. Let’s assume for this example, that I am running this locally on my host, on port 8000.

Let me break it down to clarify what an endpoint vs a route is…

1. An endpoint exists at http://localhost:8000/users. This returns a collection of all users in the data store.
2. There exists an endpoint at http://localhost:8000/users/{userId}, where {userId} represents a unique identifier for a single user. This is sometimes called the singleton object.
3. A route exists for the collection endpoint for GET /users that retrieves all users.
4. A separate route exists for the singleton endpoint for GET /users/:userId that retrieves a single user.
5. And yet another route exists for the singleton endpoint for PUT /users/:userId that updates a single user.

It’s a very small but distinct difference. You can clearly see that while there is a single API endpoint at http://localhost:8000/users/{userId}, there are two routes that serve it. They have entirely different code execution paths. If the API supported adding users (POST) or deleting users (DELETE), there could be even more routes to the same API endpoint.

See the difference? While an API endpoint may represent a single path, the code execution behind it is mapped to the action methods of the service (GET, POST, PUT, DELETE, etc). As such, a potential vulnerability in the code for one route may be very different than another. But they are tied to the same endpoint.

So what does this all mean?

So, let’s go back to Manuel’s original question. Should he be submitting one or two reports?

Well, it’s clear he is actually referring to two separate endpoints in his example, so there should be two.

But let’s assume for a moment that the API endpoint paths represented the same URI. Now, it’s not as clear. In a black-box test, you may not know how the code is written to determine if it’s an entirely separate code execution path or a big ass if statement checking different methods in the same function.

But even then, if you trace through it, it’s still a different code execution path. So, if you see two different ways to get there, it is two reports.

Here’s my rule. It’s better to do a bit more work and separate the reports, and let security triage decide if they should be merged. Don’t fret; they’ll throw the dupe flag on the case if you’re wrong. But more often than not, they will keep them separate, which means you have a better chance of being remunerated as separate issues.

Conclusion

Understanding the difference between API routes and endpoints is crucial for effective API security testing and hacking. Hopefully, I’ve clarified the difference here for you.

Have your own thoughts on the subject? Awesome! Share them with me over on Twitter/X. Looking forward to the conversation!

One last thing…

Have you joined The API Hacker Inner Circle yet? It’s my FREE weekly newsletter where I share articles like this, along with pro tips, industry insights, and community news that I don’t tend to share publicly. Subscribe at https://apihacker.blog.