Versioning on API request

[Nio]

Hi guys,

I wanted to ask a question about version numbers on API request. E.g. trains?version=123456789123

I have been checking the documentation (with google translate) and didn't give me proper understanding of it :D According to translate, it says that " versioning deletes the trains that have not been updated the version number specified by the response."

My question is that I have been checking the trains with "trains/2019-01-16" API request. If I want to update some of the fields using this version number, I lost track how to use it.

example:

"trains/2019-01-16" returns something like this (key is version number and train numbers are in the value):

{246481476177: [1],
 246473461035: [2],
 246504296705: [3, 357],
 246479326503: [4],
 246504254547: [5, 9527, 52134],
 246487529880: [6],
 246509881747: [7],
....}

Do I need to query all of these version numbers till it gets somewhere? Or are there any other way to classify proper train information per day? Also, I would appreciate if somebody explains how this version numbers are generated? Does bigger version number means what? Can I query some API to get only version numbers per specific date? How can I use this as a reference?

Another example is that:

    If I query only "trains?" on every 30 seconds, I get results given below (same version numbers for some trains) and If I query "trains?version=246585850365", it results in ~280 train numbers with different version numbers :) What does that mean now? :)

173 - 246585781150
386 - 246585781150
8666 - 246585781150
9056 - 246585781150
9832 - 246585781150
9839 - 246585781150

(1-2 min break)

22 - 246585850365
24 - 246585850365
954 - 246585850365
1636 - 246585850365
3495 - 246585850365
8465 - 246585850365
9057 - 246585850365
9060 - 246585850365
64018 - 246585850365

To sum up, I want to get an understanding how can I get daily correct information about trains with their scheduled, actual timestamps as well as their cause related information.

Thank you so much in advance for your time.

Br, nio

[Petja Touru]

Hi,

Version number is automatically incremented when data is updated.

After the initial fetch without "version" parameter, you can specify that parameter with the highest version number you had in the previous response, to get trains changed since. So, when you're making request by using the exactly same "version" parameter, changes start cumulating and you start getting more and more rows on each request.

And because the nature of the data, you can have same train in consecutive API requests with the different version number.

I hope this clears it out!

--
Petja

[Nio]

Hi Petja,

First of all, thank you so much for the answer.

So, if I understood correctly, Would this be good approach?

initial_version_number = get_max_version_number_from("trains?")

wait(X min) -- during this time it will gather data for initial_version_number (I think this is limited to 2500 object?, I can also have a function to check this that it doesnt exceed e.g. 2000 object)

# After waiting, I can query for the data using initial_version_number
data = get_data_using("trains?version=initial_version_number")

After getting the data, I can compare initial_version_number and version numbers came with data object. E.g. Lets say initial_version_number was 15 and I received [1, 2, 5, 6, 7, 12, 15, 17, 18] version numbers with data object. I can find the next version number after 15 which is 17 (this should also contain further data after this), and do the similar stuff again (wait a bit to gather next data for that version number (17 this time), fetch it and go with the next version number).

Finally, after gathering all the data (there will be duplicates for the trains), I can use max version number for each train to get latest data for that train.

Thanks again.

Br, Nio

[Petja Touru]

Hi,

I drew this simple diagram for you. Hope it helps.

When using ?version parameter, you should never get entries with older version number than given.

--

Petja

[Solita / Heikki]

Thanks Petja for answering! The picture is very good!

Br.

Solita / Heikki

[Nio]

Thanks a lot for that Petja. :)