I am a bit confused about the api in 2.25. Before, I was able to list
dataElements of a given dataSet via
As I understand from the manual, this has changed to
Two issues in this context:
1 - I would have expected to be able to use the old syntax by adding 24 or 23
into the url - that doesn't work.
2 - the new syntax only works for the id of a dataSetElement and doesn't bring
up code nor name. fields=dataSetElements[:all] only brings up a few attribute,
but not neither code nor name.
Am I missing something? Haven't tested with other sub-ressources, yet.
Two issues in this context:
1 - I would have expected to be able to use the old syntax by adding 24 or 23
into the url - that doesn't work.
2 - the new syntax only works for the id of a dataSetElement and doesn't bring
up code nor name. fields=dataSetElements[:all] only brings up a few attribute,
but not neither code nor name.
Am I missing something? Haven't tested with other sub-ressources, yet.
The reason why there isn’t a backward compatible api is because the underlying model has changed to support overriding the categorycombo per dataset. So a dataset no longer has dataElements, but dataSetElements. The dataSetElement is a compound object consisting of both a dataelement reference and (possibly) an overridden categoryCombo. Where you haven’t overriden anything you don’t see the latter.
I am sure this has broken a few things out there.
I wonder if a non-breaking solution would be to support the same behaviour as before with the dereferencing being done behind the scenes. With the possible surprise that the response might also include a sibling categorycombo with the dataelement. And the risk that if legacy api users ignore that fact (which almost by definition they will) they will report the wrong categorycombo for the dataelement.
Or, even more transparently, any overriden categorycombo could be used to replace the categorycombo in the returned dataelement. In which case everything would look exactly as before. But users should be warned to not make any assumption about categorycombo and always return that field as part of the query. I can see that becomes a pretty ugly constraint though. Possibly the previous suggestion is safer.
Lars and/or Morten would know best the reasons for taking the plunge and doing it the way that it is done. I wasn’t in on the design discussion. Possibly over the longer term it is a cleaner implementation to have the api reflect the actual underlying changed model. Not sure.
overriding categoryCombos sounds interesting - I will look at that later. Not
sure what that means in terms of transparency of the data later on, though ...
As an implementor/3rd party developer I'd expect of course that even if the api
has changed in the current version, that it will work in the old version as
before, if that is the promise - no matter what has changed in the background.
Of course I understand that it would be a tremendous effort with lot's of error
sources, that had to be invested into adapting the old api-version - which
no-one would really want.
This brings up the question, whether it really makes sense to change the backend
profoundly every three months. Maybe it would be more adequate to have major
releases (e.g. every two years) and minor releases in between. Only in the major
releases you'd change the datamodel and the api but you'd still have the
flexibility to bring in new features in the minor releases (including new
datastructures and new api's).
At the moment I am forced to constantly install the new version as they clean
out bugs or bring some good new feature, but I always have to be prepared to
adapt backend things like the ETL process, which are always major efforts.
Are you ready for DHIS3? :-DDD
Regards, Uwe
···
Bob Jolliffe <bobjolliffe@gmail.com> hat am 3. November 2016 um 20:21
geschrieben:
The reason why there isn't a backward compatible api is because the
underlying model has changed to support overriding the categorycombo per
dataset. So a dataset no longer has dataElements, but dataSetElements.
The dataSetElement is a compound object consisting of both a dataelement
reference and (possibly) an overridden categoryCombo. Where you haven't
overriden anything you don't see the latter.
I am sure this has broken a few things out there.
I wonder if a non-breaking solution would be to support the same behaviour
as before with the dereferencing being done behind the scenes. With the
possible surprise that the response might also include a sibling
categorycombo with the dataelement. And the risk that if legacy api users
ignore that fact (which almost by definition they will) they will report
the wrong categorycombo for the dataelement.
Or, even more transparently, any overriden categorycombo could be used to
replace the categorycombo in the returned dataelement. In which case
everything would look exactly as before. But users should be warned to not
make any assumption about categorycombo and *always* return that field as
part of the query. I can see that becomes a pretty ugly constraint
though. Possibly the previous suggestion is safer.
Lars and/or Morten would know best the reasons for taking the plunge and
doing it the way that it is done. I wasn't in on the design discussion.
Possibly over the longer term it is a cleaner implementation to have the
api reflect the actual underlying changed model. Not sure.
On 3 November 2016 at 14:21, Michael Mwebaze <michael.mwebaze@gmail.com> > wrote:
> Thanks Uwe,
>
> I have been trying to figure this out as well.
>
>
>
> On 3 November 2016 at 04:04, Uwe Wahser <uwe@wahser.de> wrote:
>
>> just found the answer myself: it has to be
>> https://play.dhis2.org/demo/api/dataSets/N4fIX1HL3TQ.json?pa
>> ging=false&fields=dataSetElements[dataElement[id,code,name]]
>>
>> the other question remains: why cant I use the old syntax by adding 24 or
>> 23 to
>> the url?
>>
>> Regards,
>>
>> Uwe
>>
>> ---
>> > Uwe Wahser <uwe@wahser.de> hat am 3. November 2016 um 09:52
>> geschrieben:
>> >
>> >
>> > Dear all,
>> >
>> > I am a bit confused about the api in 2.25. Before, I was able to list
>> > dataElements of a given dataSet via
>> > https://play.dhis2.org/demo/api/dataSets/N4fIX1HL3TQ.json?pa
>> ging=false&fields=dataElements[id,code,name]
>> >
>> > As I understand from the manual, this has changed to
>> > https://play.dhis2.org/demo/api/dataSets/N4fIX1HL3TQ.json?pa
>> ging=false&fields=dataSetElements[id,code,name]
>> >
>> > Two issues in this context:
>> > 1 - I would have expected to be able to use the old syntax by adding 24
>> or 23
>> > into the url - that doesn't work.
>> > 2 - the new syntax only works for the id of a dataSetElement and
>> doesn't bring
>> > up code nor name. fields=dataSetElements[:all] only brings up a few
>> attribute,
>> > but not neither code nor name.
>> >
>> > Am I missing something? Haven't tested with other sub-ressources, yet.
>> >
>> > Thanks,
>> >
>> > Uwe
>> >
>> > _______________________________________________
>> > Mailing list: https://launchpad.net/~dhis2-users
>> > Post to : dhis2-users@lists.launchpad.net
>> > Unsubscribe : https://launchpad.net/~dhis2-users
>> > More help : https://help.launchpad.net/ListHelp
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~dhis2-users
>> Post to : dhis2-users@lists.launchpad.net
>> Unsubscribe : https://launchpad.net/~dhis2-users
>> More help : https://help.launchpad.net/ListHelp
>>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~dhis2-users
> Post to : dhis2-users@lists.launchpad.net
> Unsubscribe : https://launchpad.net/~dhis2-users
> More help : https://help.launchpad.net/ListHelp
>
>
like you have observed, the Web API versioning applies to query parameters, responses and most things, but not the metadata model entirely. This because we currently do not have a “data transfer object” layer between the DHIS 2 metadata model and what we render in the API. As a consequence you might see breaking changes in the metadata model, such as for associations between objects.
We are working on this long-term, and trying to keep the changes to a minimum. Note that we do not rename fields or make unnecessary model changes, and that we documented such changes in the upgrade notes (see Web API):
The reason why there isn’t a backward compatible api is because the underlying model has changed to support overriding the categorycombo per dataset. So a dataset no longer has dataElements, but dataSetElements. The dataSetElement is a compound object consisting of both a dataelement reference and (possibly) an overridden categoryCombo. Where you haven’t overriden anything you don’t see the latter.
I am sure this has broken a few things out there.
I wonder if a non-breaking solution would be to support the same behaviour as before with the dereferencing being done behind the scenes. With the possible surprise that the response might also include a sibling categorycombo with the dataelement. And the risk that if legacy api users ignore that fact (which almost by definition they will) they will report the wrong categorycombo for the dataelement.
Or, even more transparently, any overriden categorycombo could be used to replace the categorycombo in the returned dataelement. In which case everything would look exactly as before. But users should be warned to not make any assumption about categorycombo and always return that field as part of the query. I can see that becomes a pretty ugly constraint though. Possibly the previous suggestion is safer.
Lars and/or Morten would know best the reasons for taking the plunge and doing it the way that it is done. I wasn’t in on the design discussion. Possibly over the longer term it is a cleaner implementation to have the api reflect the actual underlying changed model. Not sure.