Different route param parsing behavior between POST and GET requests

[yinpeng-sigma]

Trying to adopt https://google.aip.dev/136 and use :customMethod to model non-standard operations.

The path definition I'm using is /books/:bookId\\:upVote.

The path params captured by express is different in POST and GET requests: in POST requests the :upVote postfix is correctly excluded from the bookId param, but in GET requests the :upVote is included in the bookId param captured.

Wondering why is this? And is this behavior something I can depend on?

express version: 4.21.0

Thanks!

[krzysdz]

The code does not differentiate between methods at all. All paths are turned into regular expressions using path-to-regexp in the same way.

Processing steps

1. app.METHOD
   

   express/lib/application.js

   Lines 485 to 502 in dac7a04

   	/**
   	* Delegate `.VERB(...)` calls to `router.VERB(...)`.
   	*/
   	methods.forEach(function(method){
   	app[method] = function(path){
   	if (method === 'get' && arguments.length === 1) {
   	// app.get(setting)
   	return this.set(path);
   	}
   	this.lazyrouter();
   	var route = this._router.route(path);
   	route[method].apply(route, slice.call(arguments, 1));
   	return this;
   	};
   	});

2. Router.METHOD()
   

   express/lib/router/index.js

   Lines 517 to 524 in dac7a04

   	// create Router#VERB functions
   	methods.concat('all').forEach(function(method){
   	proto[method] = function(path){
   	var route = this.route(path)
   	route[method].apply(route, slice.call(arguments, 1));
   	return this;
   	};
   	});

3. Route.METHOD() (called by app.METHOD() or Router.METHOD())
   

   express/lib/router/route.js

   Lines 206 to 230 in dac7a04

   	methods.forEach(function(method){
   	Route.prototype[method] = function(){
   	var handles = flatten(slice.call(arguments));
   	for (var i = 0; i < handles.length; i++) {
   	var handle = handles[i];
   	if (typeof handle !== 'function') {
   	var type = toString.call(handle);
   	var msg = 'Route.' + method + '() requires a callback function but got a ' + type
   	throw new Error(msg);
   	}
   	debug('%s %o', method, this.path)
   	var layer = Layer('/', {}, handle);
   	layer.method = method;
   	this.methods[method] = true;
   	this.stack.push(layer);
   	}
   	return this;
   	};
   	});

4. Layer() constructor
   

   express/lib/router/layer.js

   Line 45 in dac7a04

   this.regexp = pathRegexp(path, this.keys = [], opts);

I've tried to write a simple example that could reproduce your issue (using 4.21.2), but it seems to work as expected:

const express = require("express");

const app = express();

app.get("/books/:bookId\\:upVote", (req, res) => {
    console.log("GET book upvote with params", req.params);
    res.send("ok");
});
app.post("/books/:bookId\\:upVote", (req, res) => {
    console.log("POST book upvote with params", req.params);
    res.send("ok");
});

const server = app.listen(0, "127.0.0.1", async () => {
    const {port} = server.address();
    const url = `http://127.0.0.1:${port}/books/123:upVote`;
    await fetch(url);                                  // GET book upvote with params { bookId: '123' }
    await fetch(url, { method: "POST", body: "abc" }); // POST book upvote with params { bookId: '123' }
    server.close();
});

[i-m-abbhay]

As @krzysdz already said in the comment. I also think we can depend on consistent behavior if the route string is identical (including the escaped colon) and routing order is the same. Method (GET or POST) doesn;t seem to affect param parsing.

It might be the case that @yinpeng-sigma have wrote /books/:bookId:upVote accidentally (missing the escape), In this case express will see two adjacent params: bookId and upVote. With no delimiter between them, the first param becomes effectively greedy and swallows the literal :upVote text into :bookId which renders upVote as empty/undefined.

[Shubhamkahar196]

Hi @yinpeng-sigma,

As mentioned by @krzysdz and @i-m-abbhay, Express uses path-to-regexp internally for all route definitions, and the parsing logic is identical for every HTTP method (GET, POST, etc.). The difference you’re seeing is most likely due to a small typo or missing escape in the route definition.

Make sure your route is defined with an escaped colon (\:) like this:

app.get("/books/:bookId\:upVote", handler);
app.post("/books/:bookId\:upVote", handler);

If you instead write it as /books/:bookId:upVote (without escaping), Express will interpret it as two adjacent parameters — bookId and upVote — and bookId will greedily capture :upVote, making the behavior seem inconsistent.

As long as both routes use the same escaped path and appear in the same order, parameter parsing will remain consistent across all HTTP methods.

[Talha089]

Thanks for the clear report — this is expected behavior in the sense that relying on :… as a literal “colon+token” in an Express route is fragile.

Short summary / cause

Express route parsing is powered by path-to-regexp. That library does not reliably support escaping a : to make it behave as a literal colon in the route pattern, and people have reported that “escaping the colon” doesn’t work as expected.
GitHub

In practice the observed GET / POST difference is most likely due to differences in how clients/transport encode the path (or how the raw request URL is presented to the router) rather than a deterministic “HTTP method changes route parsing” rule inside Express. Because the escaping/encoding is not standardized for this case, you can’t depend on consistent behavior across clients/requests. (See Express routing docs for how route patterns and : parameters are intended to be used.)
expressjs.com
+1

Reproducible test (suggestion)
Run these two requests (replace :bookId with a concrete value like 123):

GET (example)

curl -v "http://localhost:3000/books/123:upVote"

POST (example)

curl -v -X POST "http://localhost:3000/books/123:upVote"

If you want a more explicit test that isolates client-side encoding differences, percent-encode the ::

curl -v "http://localhost:3000/books/123%3AupVote"
curl -v -X POST "http://localhost:3000/books/123%3AupVote"

If the encoded form (%3A) behaves consistently, that confirms the mismatch is due to how the literal : is being encoded/seen by the server.

Recommendations / workarounds

Avoid literal : in path names. If you control the API shape, prefer a different, unambiguous path:

POST /books/:bookId/upVote or POST /books/:bookId/up-vote — easier and idiomatic for REST.

Use percent-encoding on the client. If you must use a literal :upVote suffix, ensure clients send %3AupVote in the path (i.e. encodeURIComponent the path segment). That tends to give consistent behavior because the router sees the encoded character explicitly.

Match-and-strip fallback inside a single route. If you can’t change clients, use a single route that captures the whole trailing segment and split it in your handler:

app.all('/books/:bookSegment', (req, res, next) => {
// bookSegment might be '123:upVote' or '123'
const raw = req.params.bookSegment;
const bookId = raw.replace(/:upVote$/, '');
// continue handling by method
if (req.method === 'POST' && raw.endsWith(':upVote')) {
// handle upVote
} else {
// normal handling
}
});

Use query param or header for the “custom method” (e.g. /books/:bookId?custom=upVote or X-Custom-Method: upVote) — avoids path parsing headaches altogether.

Why this is unlikely to be fixed by “escaping”

Multiple discussions and issues indicate path-to-regexp and many routing implementations don’t treat : as a stable way to match a literal colon in the route syntax — escaping a colon is not a supported/portable route pattern. For that reason, escaping-based approaches are fragile and not reliable across versions/clients.
GitHub
+1

[Shubhamkahar196]

Thanks @Talha089 for the clear and detailed explanation — that clarifies it well.

It makes sense that relying on a literal : is fragile since path-to-regexp doesn’t officially support escaping it. I’ll refactor my routes to use a cleaner pattern like /books/:bookId/upVote or percent-encode (%3A) the colon if needed. Appreciate the insights and examples — very helpful!