API docs and Stoplight

Development - Développement
1

Hello all, and thanks for help earlier.

I have figured out that some of the stuff found on Using the API is not up to date. But still VERY helpful as it describes entry point and most parameters/defaults.

However, the Stoplight stuff (thanks @Rene !) is great seems to be up to date (generated from the source)?

Being a total newbie, I am unsure of certain things - Here is an example I ran into when I (unsuccessfully) tried to import/update organisation units using the section for create an orgunit.

You will see that certain properties/objects are listed as required (externalAccess, favorite, leaf).

Are these really required and what what do they mean/is that documented? (I am guessing false, false, true (unless level-1 org). For leaf I supplied the required level anyway…

The Using the API are much less sting wrt what needs to be supplied …

Thanks for your time!

1 Like
2

Hi!
You got that right. The documentation is manually maintained which is hard to always keep it in sync with the actual API. The OpenAPI (stoplight) on the other hand is generated from the declarations (code) so it is always up to date.

However, the extraction and translation from code is not perfect yet. The required status is on of the things that isn’t always analysed correctly. We will work on that. None of externalAccess, favorite, leaf should be required, level is.

I would recommend to to start with a minimal set of properties that seem reasonable to you. Should you be missing a field the errors will let you know and you can add them.

2 Likes
3

Thanks @JanBernitt I had a minimal set of data - the API called via a python-wrapper (dhis2.py)
The error messages I got back where misleading - it claimed that I had not supplied mandatory fields.

The gory details: I sent this org-data:
[{'name': 'Oslo', 'shortName': 'Oslo', 'code': '03', 'openingDate': '1970-01-01T00:00:00.000', 'level': 2, 'parent': {'id': 'hLM62ENwRYD'}}]
(Seemed like a decent subset of information to send - matching what other docs describe)

Below is the error message I got - you will see that it claims not to have received name/shortname etc.
So I (temporary)gave up on the API and created a csv-file to import - but we are going to do ALOT of automated-imports so I would like to use the API.
I realize the error could be in the wrapper, so knowing that the ‘required’ fields are not necessary required helps a lot.

Does anyone savvy recognized the stupid noob-error I might have made? I am just confused by the error message …

[E 240227 10:17:57 orgUnitImport:102] Import failed: code: 409, url: https://test-dhis2.fhi.no/api/organisationUnits?importStrategy=CREATE_AND_UPDATE&identifier=CODE&importMode=VALIDATE&importReportMode=DEBUG, description: {"httpStatus":"Conflict","httpStatusCode":409,"status":"ERROR","message":"One or more errors occurred, please see full details in import report.","response":{"responseType":"ObjectReport","uid":"FOLL4lZKGsl","klass":"org.hisp.dhis.organisationunit.OrganisationUnit","errorReports":[{"message":"Missing required property name","mainKlass":"org.hisp.dhis.organisationunit.OrganisationUnit","errorCode":"E4000","errorKlass":"java.lang.String","errorProperty":"name","errorProperties":["name"]},{"message":"Missing required property shortName","mainKlass":"org.hisp.dhis.organisationunit.OrganisationUnit","errorCode":"E4000","errorKlass":"java.lang.String","errorProperty":"shortName","errorProperties":["shortName"]},{"message":"Missing required property openingDate","mainKlass":"org.hisp.dhis.organisationunit.OrganisationUnit","errorCode":"E4000","errorKlass":"java.util.Date","errorProperty":"openingDate","errorProperties":["openingDate"]}]}}

4

I don’t know the python wrapper, what strikes me as wrong is:

  • you send an array of objects
  • you use single quotes

When I send the following with a POST to /api/organisationUnits it is accepted and returns 201 Created.

{"name": "Oslo", "shortName": "Oslo", "code": "03", "openingDate": "1970-01-01T00:00:00.000", "level": 2, "parent": {"id": "ImspTQPwCqd"}}

Note that I had to change the parent ID to an ID that existed in my testing environment on level 1.

2 Likes
5

You probably needs to send object instead of array to reslove the missing property error.

1 Like
6

Wow. Thanks. I am so python-used that (double)single quotes are equivalent.

Edit: I have used single quotes earlier (for another entrypoint (dataValueSets) and had no problems. I will probably have to check the wrapper - but might also try out double quotes)