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. .. raw:: html 
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. .. raw:: html 
    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 ------------------------ .. raw:: html 
    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: .. raw:: html 
    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 .. raw:: html 
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 ------------------------------------- .. raw:: html 
POST /api/v1/metadata
*Payload* :: {"xform": , "data_type": "", \ "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 ^^^^^^^^^^^^^^^^ .. raw:: html 
DELETE /api/v1/metadata/{pk}