Align api endpoints structure with open-api guidelines

[ayushin]

Hi,

Let me start by saying I think mailcow is a truly great and unparalleled product in its own class and that I don't want to start a war here, even though I noticed certain resistance of the team to the external ideas, so I am going to give a try.

I've noticed that the API structure does not really follow the open-api guidelines (https://swagger.io/blog/api-design/api-design-best-practices/) and even REST principals, where the whole idea of the resource URI is roughly resource/identifier/operation, e.g. GET /domains/1234 or DELETE /domains/1234 or PATCH /domains/1234 etc

This uniformity allows to use open-api in multiple applications and automatically generate clients in various languages.

Was there any reason to take a non-standard approach to structuring and naming the api end-points?

If not, I think it really would be worth considering for API v2 because at the moment this prevents using this API out-of-the box in a number of applications, which is what the open-api intended for.

Again, excuse my interference, we want to use mailcow for a larger scale customer base deployment, and this is one of the thing which is in our way.

[axello]

I second this idea. I've been tinkering with the idea to make a mobile app to easily add aliases to domains, and if an OpenAPI spec would be available, half of the development work could be automated.
And there is one now, available here: https://demo.mailcow.email/api/ !