Metadata

This endpoint provides access to form metadata, for example, supporting documents, media files to be used in the form, source documents and map layers.

• pk - primary key for the metadata

• formid - the form id for a form

• format - is the extension of a file format e.g png, csv

Permissions

This endpoint applies the same permissions someone has on the form.

Get list of metadata

Returns a list of metadata across all forms requesting user has access to.

GET /api/v1/metadata

HTTP 200 OK

[
    {
        "data_file": "",
        "data_file_type": null,
        "data_type": "public_link",
        "data_value": "http://mylink",
        "id": 406,
        "url": "https://api.ona.io/api/v1/metadata/406",
        "xform": 328
    },
    {
        "data_file": "username/form-media/a.png",
        "data_file_type": "image/png",
        "data_type": "media",
        "data_value": "a.png",
        "id": 7100,
        "url": "https://api.ona.io/api/v1/metadata/7100",
        "xform": 320
    },
    ....
]

Get list of metadata for a specific form

The form endpoint, /api/v1/forms/formid, contains a metadata field has list of metadata for the form. Alternatively, you can supply the query parameter xform with the formid as the value.

GET /api/v1/metadata?xform=formid

HTTP 200 OK

[
    {
        "data_file": "username/form-media/a.png",
        "data_file_type": "image/png",
        "data_type": "media",
        "data_value": "a.png",
        "id": 7100,
        "url": "https://api.ona.io/api/v1/metadata/7100",
        "xform": 320
    },
    ....
]

Get a specific metadata

GET /api/v1/metadata/{pk}

curl -X GET https://api.ona.io/api/v1/metadata/7100

HTTP 200 OK

{
    "data_file": "username/form-media/a.png",
    "data_file_type": "image/png",
    "data_type": "media",
    "data_value": "a.png",
    "id": 7100,
    "url": "https://api.ona.io/api/v1/metadata/7100",
    "xform": 320
}

If the metadata is a file, appending the extension of the file type would return the file itself e.g:

GET /api/v1/metadata/{pk}.{format}

curl -X GET https://api.ona.io/api/v1/metadata/7100.png -o a.png

Alternatively, if the request is made with an Accept header of the content type of the file the file would be returned e.g

GET /api/v1/metadata/{pk} Accept: image/png 

curl -X GET https://api.ona.io/api/v1/metadata/7100 -H "Accept: image/png" -o a.png

Add metadata or media file to a form

POST /api/v1/metadata

Payload

       {"xform": <formid>, "data_type": "<data_type>", \
"data_value": "<data_value>"}

Where:

• data_type - can be ‘media’ or ‘source’ or ‘supporting_doc’

• data_value - can be text or a file name

• xform - the form id you are adding the media to

• data_file - optional, should be the file you want to upload

Example:

curl -X POST -d "{"data_type": "mapbox_layer", "data_value":"example||https://api.tiles.mapbox.com/v3/examples.map-0l53fhk2.json||example attribution", "xform": 320}" https://api.ona.io/api/v1/metadata -H "Content-Type: appliction/json"

HTTP 201 CREATED

{
"id": 7119,
"xform": 320,
"data_value": "example||https://api.tiles.mapbox.com/v3/examples.map-0l53fhk2.json||example attribution",
"data_type": "mapbox_layer",
"data_file": null,
"data_file_type": null,
"url": "https://api.ona.io/api/v1/metadata/7119.json"
}

Media upload example:

        curl -X POST -F 'data_type=media' -F 'data_value=demo.jpg' \
-F 'xform=320' -F "data_file=@folder.jpg" https://api.ona.io/api/v1/metadata.json

HTTP 201 CREATED

{
"id": 7121,
"xform": 320,
"data_value": "folder.jpg",
"data_type": "media",
"data_file": "ukanga/formid-media/folder.jpg",
"data_file_type": "image/jpeg",
"url": "https://api.ona.io/api/v1/metadata/7121.json"
}

Link XForm or Dataview as a media to a form

It is possible to link another form or a dataview as a csv media resource to a form, the linked form will be downloadable by ODK Collect and Enketo as media. The data_type parameter will be ‘media’m the xform parameter will be the form id you are adding the media to and the data_value param is a string of the form “xform [form id] [filename]” or “dataview [dataview id] [filename]”.

Where:

• [form id] - is the numeric id of the form

• [dataview id] - is the numeric id of the dataview

• [filename] - name of file for the linked resource, e.g fruits -> fruits.csv

Link XForm or Dataview as a media example:

curl -X POST -F 'data_type=media' -F 'xform=320' -F 'data_value="xform 328 places"' https://api.ona.io/api/v1/metadata.json

HTTP 201 CREATED

{
"id": 7121,
"xform": 320,
"data_value": "xform 328 places",
"data_type": "media",
"url": "https://api.ona.io/api/v1/metadata/7121.json"
}

Link XForm as a GeoJSON media attachment example:

curl -X POST -F 'data_type=media' -F 'xform=320' -F 'data_value="xform_geojson 328 places"' -F 'extra_data='{"data_title": "fruits", "data_simple_style": true, "data_geo_field": "geofied_1", "data_fields": "field_1,field_2"}'' https://api.ona.io/api/v1/metadata.json

HTTP 201 CREATED

{
"id": 7121,
"xform": 320,
"data_value": "xform_geojson 328 places",
"data_type": "media",
"extra_data": '{"data_title": "fruits", "data_simple_style": true, "data_geo_field": "geofied_1", "data_fields": "field_1,field_2"}'
"url": "https://api.ona.io/api/v1/metadata/7121.json"
}

Create XForm meta permissions

Set meta permissions for a specific form by passing two roles that are pipe delimited. First role indicates editor default role and the other is the dataentry default role.

Example

curl -X POST -F 'data_type=xform_meta_perms' -F 'xform=320' -F 'data_value="editor-minor|dataentryonly"' https://api.ona.io/api/v1/metadata.json

HTTP 201 CREATED

Delete Metadata

DELETE /api/v1/metadata/{pk}