Deep Updating Project and Form Details

(introduced: version 0.7)

When managing a large deployment, it can be necessary to make sweeping changes to all Form States and Assignments within it at once—when rolling out a new Form, for example, or replacing a deprecated version with a new revision.

For this purpose, we offer this PUT resource, which allows a deep update of Project metadata, Form metadata, and Form Assignment metadata at once and transactionally using a nested data format.

One important mechanic to note immediately here is that we follow true PUT semantics, meaning that the data you provide is not merged with existing data to form an update. With our usual PATCH endpoints, we do this kind of merging and so data that you don't explicitly pass us is left alone. Because we allow the deletion of Form Assignments by way of omission with this API, we treat all omissions as an explicit specification to null the omitted field. This means that, for example, you must always re-specify the Project name, the Project description, and archival flag with every PUT.

This adherence to PUT semantics would normally imply that Forms could be created or deleted by way of this request, but such an operation could become incredibly complex. We currently return a 501 Not Implemented error if you supply nested Form information but you do not give us exactly the entire set of extant Forms.

You can inspect the Request format for this endpoint to see the exact nested data structure this endpoint accepts. Each level of increased granularity is optional: you may PUT just Project metadata, with no forms array, and you may PUT Project and Form metadata but omit assignments from any Form, in which case the omitted detail will be left as-is.