I learnt a bit about the new endpoint at the annual conference, and I remember someone mentioning a final version it would be supported on, but I cannot find that information anywhere.
Hi @plinnegan - this is not decided yet, but we will not deprecate in 2.37 or 2.38. Do you have any input to the decision from your perspective?
@Markus we are on the decision to go for the legacy vs the new tracker API for a large (volume and scope) integration on two fronts. So we have questions:
- How would the transition impact the Android SDK? Would the Android SDK switch under the hood without changing its own (Java) API?
- Given it’s new, and there are still features being added according to the New Tracker page, what is your recommendation for production workloads starting with 2.35 or 2.36?
- How complex is, in your experience, switching from the legacy API to the new API? Property names have changed, and it’s possible to use a flat/nested structure. Is there anything else to consider? A section in the guide for transitioning would be handy for other implementations I think.
Beat to me it! Thanks David.
Thank you for the questions, I am sure we are creating a thread here that will be interesting to others as well
One thing worth mentioning before answering the detailed questions below: The new endpoint for importing tracker data is a deep reimplementation/refactor. There is also functionality in the new endpoints for getting/retrieving tracker data, but these are just a thin translation layer on top of the old services. The translation layer is there to provide a response format that matches better what the new tracker importer expects.
On Android, the new SDK will use the new endpoints, and the switch will be under the hood as you suspected. For a consumer of the SDK the switch from old to new services will be transparent.
The base recommendation would be to go for the new endpoint if that is possible - this is the one we will put most resources into for future optimizations and new functionality.
The endpoint was not officially released until 2.36, if you would plan to start using the unofficial alpha version that was there from 2.35 we should have a closer look before recommending this.
The endpoint is feature complete as far as we know, with one clear exception that might or might not be relevant for you: The server to server SYNC functionality from the old tracker importer has not yet been reimplemented in the new importer. This will be implemented in a future version but probably not back ported. The old tracker importer will not be deprecated until the functionality for SYNC is reimplemented and released, but we do not know what version this will be yet.
We created a document to track the differences between the endpoints that might be helpful.
@jose @dhis2-android might perhaps comment on this topic as well.
from the Android SDK perspective, the switch to the new tracker import will be transparent for the applications, the SDK API won’t change. Actually, the SDK will implement both importers under the same API method: the old one could be used for any DHIS2 version, the new one could only be used for >= 2.36.
The mechanism to decide which importer to use is not fully implemented yet, but there would be these two options at least:
- the Android Settings App will include a checkbox to use the new tracker importer. The SDK will use this value to switch between the importers. If you are using the official Android app or any app consuming the SDK, you could use this property to decide which importer to use.
- the SDK will include a property at application level to switch between importers. This property could be used by custom applications.
The next version (scheduled for October) will only include support for data upload using the new importer. Data download will still use the old endpoint.
About our experience migrating to the new API, it is true that models have changed but in most of the cases they are just a refactor of the property names. We have just created these new models and a service to do the translation depending on the DHIS2 versions we are talking to. Relationship model has changed, but it is a simple change and it even simplifies the model.
In our case, the most important change was the ASYNC behavior of the new importer. The importer also accepts SYNC imports, but we preferred to use ASYNC mode to make it more robust: the server returns an jobId immediately, so there is not risk for timeouts in case the import takes too long. Also, if the application stops or the connection is suddenly broken, we can recover the import summary when the application is restarted. This implies an extra job in the logic, but it is worthy.
Hope it helps!