set_config APIs

[imobachgs]

Some time ago, we introduce in storage the SetConfig method, exposed as PUT /storage/config and GET /storage/config. The storage settings are rather complex so they are not processed by the HTTP layer at all. We might consider them as a document that explains how to create the storage layout.

The problem is that we started to, in my opinion, abuse this pattern.

For instance, let's thing about the files API. From an HTTP perspective, I would expect something like:

• GET /files to get the list of files.
• POST /files to add a new file.
• DELETE|PUT /files/:name to delete or update files.
• DELETE /files to clean-up the files.

Of course, we do not need all this methods (we can get rid of the /files/:name by now). But what we have is:

• PUT /files/config which receives the list of files.

So if you are using the HTTP API and you want to add a file, you need to retrieve the whole list, add your file and put all of them together again. Sure, we could have a flag to indicate that you just want to add a file but that's exactly the intention behind using POST, right?

The same happens with the DASD API: we have a set_config method that takes care of everything during the auto-installation. Actually, the logic is implemented in the client while I would have expected it to be in the store. However, this case is slightly different, as we still rely on D-Bus.

What's the problem?

1. We are using the HTTP API just as a transport layer in those cases. It is just fine to use PUT to set configuration values, but when we are creating/removing stuff, I think we should leverage HTTP semantics.
2. Consistency. There are APIs (e.g., network or script) that rely on HTTP semantics, while others are just importing the Agama configuration file.
3. The HTTP API is highly coupled to the Agama configuration file.
4. The HTTP API in those cases is less flexible.

I see two "benefits" for a full SetConfig based approach:

1. You do not need to distinguish between the configuration file and the params you pass to the HTTP API. It would simplify the code.
2. You need to do several requests, although I do not think it is a problem at all.

My proposal

We need to decide the approach we want to follow and be consistent. After all, we are considering our HTTP API as part of our public API.

Let's the discussion begin. 😉

PS: storage is out of discussion.

[imobachgs]

I have rephrased the discussion a bit in a more neutral manner.

In order to keep the SetConfig approach, which is beneficial in the storage case, we could use a better PATCH when we need to add/remove stuff. After all, thats the idea behind PATCH.

In that way, you could add a file or a script by performing a PATCH /config request (instead of replacing it with PUT). At this point, we use PATCH for partially updating the configuration (e.g., in software), but we do not use it to add/remove elements from collections.

Of course, that's only relevant if we want to support that use case.