OpenRosa Form Submission API

This is the fully standards-compliant implementation of the OpenRosa Form Submission API. We will not attempt to redocument the submission part of the standard here, but please read further for information about updating submissions with new data.

Some things to understand when using this API for any reason:

• ODK Central will always provide an X-OpenRosa-Accept-Content-Length of 100 megabytes. In reality, this number depends on how the server has been deployed. The default Docker-based installation, for example, is limited to 100MB at the nginx layer.

• The xml_submission_file may have a Content Type of either text/xml or application/xml.

• Central supports the HEAD request preflighting recommended by the specification, but does not require it. Because our supported authentication methods do not follow the try/retry pattern, only preflight your request if you want to read the X-OpenRosa-Accept-Content-Length header or are concerned about the other issues listed in the standards document, like proxies.

• As stated in the standards document, it is possible to submit multimedia attachments with the Submission across multiple POST requests to this API. However, we impose the additional restriction that the Submission XML (xml_submission_file) may not change between requests. If Central sees a Submission with an instanceId it already knows about but the XML has changed in any way, it will respond with a 409 Conflict error and reject the submission. Additionally, a 409 Conflict error is returned if the Submission has been deleted in Central while attempting to send further POST requests.

• Central will never return a 202 in any response from this API.

• If you haven't already, please take a look at the HTTP Request API notes above on the required OpenRosa headers.

You can use this endpoint to submit updates to an existing submission. To do so, provide additionally a deprecatedID metadata XML node with the instanceID of the submission you are replacing. Some things to understand when submitting updates:

• The new XML entirely replaces the old XML. No merging will be performed. So your new submission must contain exactly the current data.

• If the deprecatedID you provide has already been deprecated, your request will be rejected with a 409 Conflict and a useful error message.

• If the submission you are deprecating had media files uploaded for it, any of those that are still relevant will be carried over to the new version by filename reference. Any files you provide will overwrite these carryovers.

• Just as with initial submission, you can send multiple requests to this endpoint to submit additional media files if they do not comfortably fit in a single request. Also the same as initial submission, you'll need to provide exactly the same XML to make this happen. For updates, this will need to include the deprecatedID.