GET /api/v2/importer/{name} is not consistent on the period definition response

[carlosthe19916]

Context:
There is an ongoing effort to implement CREATE/EDIT operations through the UI

If I create an Importer setting the period in certain Unit. E.g. weeks. But when I fetch the same importer using GET /api/v2/importer/{name} the period field contains unpredictable units like 1year 1month 24days 7h 26m 24s.

This is a problem for the UI because there isn't a predictable way of parsing strings like 1year 1month 24days 7h 26m 24s and then allow the user to edit that.

To reproduce:

• Create an inporter of any kind and define the period=60weeks
• Fetch the same importer using GET /api/v2/importer/{name} and the definition of period will be similar to 1year 1month 24days 7h 26m 24s

How should it work?
The response of GET /api/v2/importer/{name} should define period using only one unit of measurement E.g. Instead of 1year 6 months it can return 18months.

[ctron]

The response will split this up in the highest unit possible. The UI should not expect the same string to return, but the same value. The value is a duration.

[carlosthe19916]

As long as the response uses a single unit everything should work. E.g.:

• xyz hours => valid
• xyz years => valid
• xyz years abc months xyz weeks => NOT valid as it is combining multiple units "years, months, weeks"

[jcrossley3]

I think we could store the period as a String instead of a Duration to solve this issue. It would require the introduction of some function to validate that the string could be parsed as a duration, but should be doable, I think. Maybe with a deserialize_with serde attribute?

[carlosthe19916]

If you find technical difficulties, even returning a number in milliseconds would work, then every client can convert milliseconds to anything without dealing with Strings. There is no reason to complicate things with responses like xyz years abc months xyz weeks. A clear example is in the issue description where the response was 1year 1month 24days 7h 26m 24s.

[ctron]

I've seen so many errors when storing durations as a plain number. As it's never clear what unit it is. Unless you name fields something like period_ms.

The idea of having a human readable string is to make it easier for people working on the command line, with a simple http client. However, I agree that this might not be very ergonomic working with code. Though in the end, the problem would stay the same. If the user enters 36228384000 ms as a duration, you will need to format this in the UI in a user friendly way.

An alternative could be to serialize this as an unsigned integer and accept both string or integer when deserializing. Parsing a string as humantime. This way one could still work on the command line with 1 day when submitting requests.

[jcrossley3]

Maybe I wasn't clear. I'm suggesting we store the user-entered string in the db, e.g. "32s" or "25days" or "1w" or even "1 year 2 mos 7 days" if @carlosthe19916 wants to eventually extend that ability to the user.

But on the backend, we always deal with a humantime string, so it's always obvious what the duration is. And whatever the user enters is what the user gets back, assuming it's parseable by humantime, otherwise an error is returned.

What's wrong with that?

[ctron]

What's wrong with that?

That you always need to parse the string when retrieving it from the database. What if foo bar ends up in that column? You'd also need to deal with parsing errors then.

The value is normalized to a numeric value of a specific type in the database. The humantime aspect is only present on the API. In my opinion, it should stay that way.

[carlosthe19916]

@ctron @jcrossley3 what concrete solution do you guys propose for the clients (other apps) to deal with strings like 1year 1month 24days 7h 26m 24s?

• If you consider it is the client's responsibility, let's close this issue. I will adapt the UI to the current status of the REST API.
• If you consider we can do something to make clients (other apps, not curl, not humans) to interact with our REST API, then what is the concrete solution? I'll leave the final decision to you guys. Whatever you decide I will accept it.

Kind regards!

[jcrossley3]

What's wrong with that?

That you always need to parse the string when retrieving it from the database.

True. Seems a small price to pay to facilitate user friendliness. I think it's worth the effort for the user to "read exactly what he wrote". Bonus is that it's plain to see the period in the database, i.e. I don't have to know what the units of the value stored are.

What if foo bar ends up in that column? You'd also need to deal with parsing errors then.

It wouldn't end up there through the UI/API, thanks to the deserialize_with fn tossing an error.

I can work up a PR if you're open to it.

[helio-frota]

I think it's worth the effort for the user

whatever is better for the user is good ofc 👍

[ctron]

I think it is a mistake. And I don't think we are solving any real problem for a user here. If a user decides to enter a weird (valid) time period, then we currently normalize this in the database and render it (as friendly as possible) on the API. That might not be the exact same value, but good enough.

Changing to be a string in the database won't solve the situation on the frontend, it will make the backend more complicated and the user can still enter weird (valid) values. Which one user might prefer, while another user with the system might not.

That's my opinion and I leave it with that.