Survey‐Tree association - FarmRadioHangar/uliza-core-apis GitHub Wiki

The relation that associates a VOTO survey with a registration tree is managed from the voto_survey_registration_tree API endpoint, described in the relevant section of the Uliza API documentation.

Details

Internally, the registration system relates surveys to trees through the uliza_voto_survey_registration_tree database table.

Field	Key	Extra
id	PRI	auto_increment
voto_survey_id	UNI
voto_tree_id

We can use the following curl request to query this relation:

curl http://dev.ulia.fm/api/v1/voto_survey_registration_tree/ 

Tip: If Python is installed, you can use the the JSON Tool to pretty-print the output: curl -s http://dev.uliza.fm/api/v1/voto_survey_registration_tree/ | python -m json.tool

[
    {
        "id": 1,
        "voto_survey_id": 115,
        "voto_tree_id": 6
    },
    {
        "id": 2,
        "voto_survey_id": 612,
        "voto_tree_id": 1142
    }
]

Or open http://dev.uliza.fm/api/v1/voto_survey_registration_tree/ in a web browser to access the browsable API.

Because of the voto_survey_id field uniqueness constraint, the data in the uliza_voto_survey_registration_tree table forms a partial function, mapping surveys to trees. In the following example, we will consider the below tuple, which links the survey with id 512 to tree id 42.

id	voto_survey_id	voto_tree_id
1	512	42

Assuming an entry does not already exist for this survey, the following API request can be used to create this association.

curl \
  -XPOST \
  -H 'Content-Type: application/json' \
  -d '{"voto_survey_id": 512, "voto_tree_id": 42}' \
  http://dev.uliza.fm/api/v1/voto_survey_registration_tree/

Updating a survey

Since only one registration tree can be associated with any given survey, to associate a tree with a survey which is already linked to another tree, you must use PUT or PATCH instead of POST.

curl \
  -XPATCH \
  -H 'Content-Type: application/json' \
  -d '{"voto_tree_id": 700}' \
  http://dev.uliza.fm/api/v1/voto_survey_registration_tree/512/

If you use PUT, the voto_tree_id field must match the id of the resource you are updating. The following request is not valid and will yield an error.

curl \
  -XPUT \
  -H 'Content-Type: application/json' \
  -d '{"voto_survey_id": 1, "voto_tree_id": 700}' \
  http://dev.uliza.fm/api/v1/voto_survey_registration_tree/512/