In an HTTP application, I think about routing requests based not only on the path, but also based on the request body. For an example, think about the following two different body schemas for a PUT request against an /orders/{id} endpoint:
A
{
adminPassword: String,
status: String,
}
B
{
clientSecret: String,
deliveryAdress: Object,
}
The requests should be routed to a different controller.
Of course, the business logic could be expressed by differentiating the two requests by assigning each an individual path. But I think there is some semantic benefit in having exactly one path for all updates of a entity, in different ways.
The idea is inspired by how Erlang and Elixir allow multiple function clauses with pattern-matching.
If I understand it correctly, it would be not native and probably hard, maybe even impossible, to reflect this API structure in OpenAPI. That in itself is a strong argument against this idea.
What other arguments speak against this approach? Has this been tried before?
4
What you’re asking is essentially having the mailman deliver the packages differently based on what’s inside the package. The mailman should not be looking in there.
Other information, such as the URL, query params and headers are intended for the figurative mailman to inspect and rely on to deliver the package to the correct location.
POST bodies are not meant to be inspected while still in transit. That’s not to say it would be impossible to do so, but I’m not going to advocate for you doing so.
But I think there is some semantic benefit in having exactly one path for all updates of a entity, in different ways.
Here, we strike on the X of your XY problem. You’re not looking for a way to route POST requests to different endpoints based on their body, you’re looking for a way to have the same POST endpoint accept different bodies.
Like you said yourself, it makes semantic sense to have exactly one path. Somehow, you’ve not applied the same conclusion to having exactly one endpoint (which represents said path), which is where I think you’ve gone off the rails when looking for a solution.
Instead of trying to get the router to inspect the bodies and somehow figure out which body should go to which endpoint, have your (single) endpoint receive the JSON and figure out which type (of several options) to deserialize it into.
Any argument you make pro-one-route, I can argue is also a pro-one-endpoint argument. Any argument you make anti-one-endpoint, I can argue is also an anti-one-route argument.
It’s the same logic in either case, but going with one endpoint means you’re not needlessly involving the router in a way that it was never meant to be operated.
This answer is a frame challenge.
But I think there is some semantic benefit in having exactly one path for all updates of a entity, in different ways.
Perhaps you are not aware that what you are describing is a core design element of SOAP/WSDL based services which was a large part of the problems with the web services built upon them. When you do something like this, you are ignoring the features of HTTP designed to solve this problem, hence your struggle.
Routing requests using HTTP features designed for that purpose will make your goals much easier to achieve and your solution more easily understood and supported. Unless you can identify some specific benefit of this that cannot be achieved using HTTP features as intended, I don’t see any good reason to do this. The one caveat would be if someone had decided to do this in the past and you were required to make a backwards compatible solution. But in this case, you would be the person potentially creating that problem for someone in the future, if I understand correctly.
One of the more serious issues with this is that you may make your solution significantly more difficult to secure. For example, if you used a separate path for your admin operations, firewall rules can easily be setup to restrict access to that endpoint from only approved IP addresses/ranges. If you use a single endpoint that solution doesn’t work, and you will need something that can inspect the contents of the message and write custom rules. The risks of an error resulting in a vulnerability are much higher when you customize your security solutions.
7
Essentially this is just method overloading over HTTP.
However, given the limitations of json you would have a problem distinguishing types from each other. The obvious solution would be to add a _type field somewhere that’s easy to read.. like the path
1
Client secrets and admin passwords refer to authentication and authorization. The HTTP protocol already represents this as challenge-response authentication and the authorization header. Now, this doesn’t stop you from doing routing based on the request body. You can write code to parse the JSON payload and dispatch to a different controller, but this is outside the bounds of the HTTP standard.
To be honest, dispatching to different controllers means changes in application behavior. This is a matter of business logic, and business logic is not something that HTTP is concerned with.
As for OpenAPI? Client secrets and admin passwords become part of the description of the parameters passed to an API endpoint. OpenAPI doesn’t describe the controllers in your web application. It describes the messages you can send to the system, so your proposed routing technique could fit, but probably would not be relevant to the API spec.
But I think there is some semantic benefit in having exactly one path for all updates of a entity, in different ways.
You can have one path and different ways of updating an entity. What a user is allowed to do is authorization. Based on what the user is authorized to do, the server side application might execute different logic. The conceptual resource identified by /orders/{id} shouldn’t change based on the user, but what the user can change within that resource is not captured by HTTP. This is a separate concern specific to your application, and not generalized to how computers identify resources across a network.
From an HTTP client perspective, the controller that handles a request is entirely hidden, and irrelevant. This only becomes relevant to the maintainers of the server side application processing requests. Those people should have some knowledge of HTTP, and being that routing based on the request body is not typically supported by most web frameworks, it would violate the Principal of Least Astonishment. It may surprise people that routing works this way in your application, but the world wouldn’t end.
Choosing a solution like this should be done only if other standard approaches won’t work, and you clearly document why it doesn’t work and how to use this feature of your routing code. Otherwise, if it works better than the alternatives, there is nothing wrong with doing this.
2
What other arguments speak against this approach? Has this been tried before?
In your question, you are somewhat conflating message contents with the target of the endpoint, and give an example of two payloads. But if there are thousands? This is not a stretch, as a focused site as StackExchange is in the range of two hundred.
In both cases, the routing API will be in charge of first decoding payloads, then in running a recursive matching algorithm with no know bounds, to find the best object that best matches the payload, or throws an error, but only at the end of explosive, exhaustive search.
This screams DDoS. A very obvious, very inevitable DDoS target, in the very first steps of an API designed like this.
1