API wiki post: developers, collaborate here with API Q&As & tips you find helpful for other developers

Development - Développement
1

Hi all,
I had some questions about API requests and asked other developers in the Developers Workspace for support. I got some good responses; therefore, I thought it’d be helpful to have a wiki with helpful questions & responses that the developers in the DHIS2 Community of Practice can contribute to. Thanks!

How to help/contribute?

This is a wiki post which means all community members are welcome to edit it, add a Q&A or helpful tips then tag their CoP usernames at the end of this post. See contributors list at the end of this post.

Helpful API Q&As - API tips:

Q - Can we query for information from two different API endpoints in one request?

@RModi I would suggest to use two different queries and concatenate the result. Might be less daunting.
@tzemp You might be able to structure a single query using nested references … but if you want to access completely different resources from the api (say messageConversations and dataElementOperands) you’d probably need to make multiple requests

Q - How do we structure nested queries?

@tzemp to structure a single query using nested references, e.g. if you want to see the names of categoryOptions associated with a given program, you could use [instanceURL]/api/programs?fields=id,name,categoryCombo[id,name,categories[id,name,categoryOptions[id,name]]]

Q - How do we create filters in API requests?

@tzemp you can put the filters at the end, like: [instanceURL]/2.37.2/api/programs?fields=id,name,categoryCombo[id,name,categories[id,name,categoryOptions[id,name]]]&filter=categoryCombo.categories.name:like:Implementing

Q - How do we create more than one filter in an API request?

@tzemp you’ll need to do concatenate the filter conditions with & like &filter=object:like:something&filter=object2:eq:xyz

Q - Can we add logic to filters in API requests?

@tzemp you can specify a rootJunction if you don’t want to use AND, e.g. &filter=object:like:something&filter=object2:eq:xyz&rootJunction=OR
See Logical Operators section here:
https://docs.dhis2.org/en/full/develop/dhis-core-version-master/developer-manual.html#webapi_metadata_object_filter

Q - What is a ‘deprecated’ API end point?

@austin In general a deprecated api is set to be removed in a future version, so relying on it isn’t recommended.

Q - Why is it not recommended to use fields=*?

@austin you can specify explicit fields within the api end point so you shouldn’t need fields=* (which can create a heavy request)

Q - How can I know if there are dataSets or programStages that contain empty custom forms?

Maybe you can reuse these example API calls :slight_smile:

https://play.dhis2.org/2.36.12/api/dataSets.json?fields=id,name,dataEntryForm[id,htmlCode]&filter=dataEntryForm:!null&filter=dataEntryForm.htmlCode:null

https://play.dhis2.org/2.36.12/api/programStages.json?fields=id,program[name,id],name,dataEntryForm[id,htmlCode]&filter=dataEntryForm:!null&filter=dataEntryForm.htmlCode:null

Q - API response says I need to get an ID for a metadata object, how?

@Gassim Generally, to get an ID of a metadata object, you need to check its API endpoint, here are two important resources that will help you find your way through the API:

After that you will request the ID from the end point and use fields and filters to return the required result.

Q - What’s the fastest way to get all the results from the Event Reports app?

Is there a way to retrieve TEIs from multiple programs?

Q - How do I get all sublevels of a specific org unit - using [nested objects]
If you want to list out a nested object you need to add a children field in square brackets along with the fields you want to retrieve. Nest the children field as deep as your maximum Org unit level is. The example below fetches the four sub-levels of the org unit with the Id ImspTQPwCqd.

https://play.dhis2.org/40.0.1/api/40/organisationUnits/ImspTQPwCqd?fields=name,id,children[name,id,children[name,id,children[name,id]]]

Contributors:

@RModi
@tzemp
@Gassim
@austin
@ctejo
@redet
[add your username here after adding a contribution :pray:]

7 Likes
2

This is awesome. Thanks to all contributors! We should turn this into an API FAQ if it keeps growing :slight_smile:

3 Likes
3

Yes it’d would be great to have a reviewed version and this can remain a collaborated wiki by the community! (: I hope it grows more and more, for me it feels like sharing notes that came in handy!

There a couple of new tips that I have from @plinnegan so I will be adding them within this week. :+1::+1:

2 Likes
4

This resource is great! I use the API a lot, especially when working on data models in Power BI. Particularly, when wanting to pull SQL views to my data models - i.e the period structure, pulling comments made on tracked events, etc.

1 Like
5

Very glad to hear that. (: Thanks for the comment @mykbitz! A good reminder to keep adding input. It’s a wiki so community members are welcome to add their contributions. :+1::+1:

True! Recently, we were discussing a method to download the SQL view xls using the API

1 Like
6

I am having a challenge in creating Standard report pulling data using API (JSON format) as it ignore the blank fields. Is there any way that I can force the Aggregate API to include the blank values. I tried to use " fields=* " as recommended above but it doesn’t work because it still ignore the blanks.

Any suggestion will be appreciated

1 Like
7

@tzemp this helped me again today! Thanks! :blush:

I hope next time I wont forget that in fields we’d use brackets categories[id] where as in filter we use dot categories.id .

1 Like
8

Could you reproduce the API request in any of the play.dhis2.org instances and share the request so I or anyone else from the community might be able to figure out the issue?

Thanks!

9

Thanks @redet! :sun_with_face::pray:

1 Like