Skip to main content

Update Examples

Updating assets through the API involves sending POST requests to the URL of the asset to be updated, with an XML payload. These examples can be tested in your browser by using the page ~/http.html.

How to Update a Scalar Attribute on an Asset​

Updating a scalar attribute on an asset is accomplished by marking the attribute with act="set", and filling in the new value in the element's text. This post will update the Phone attribute of the Member with ID 20:

POST /VersionOne/rest-1.v1/Data/Member/20 HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 78

<Asset>
	<Attribute name="Phone" act="set">555-555-1212</Attribute>
</Asset>

The response is:

<Asset href="/VersionOne/rest-1.v1/Data/Member/20/173" id="Member:20:173">
	<Attribute name="Phone">555-555-1212</Attribute>
</Asset>
Remarks

The response includes the URL of the exact version of the asset that was just updated.

How to Update a Single-Value Relation on an Asset​

Updating a single-value relation is accomplished by marking the attribute with act="set", and filling the idref of the enclosed Asset element. This post will change the Owner of the Scope with ID 0 to be the Member with ID 20:

POST /VersionOne/rest-1.v1/Data/Scope/0 HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 98

<Asset>
	<Relation name="Owner" act="set">
		<Asset idref="Member:20" />
	</Relation>
</Asset>

Whereas this post will change the Owner of the Scope with ID 0 to nobody (that is, NULL):

POST /VersionOne/rest-1.v1/Data/Scope/0 HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 67

<Asset>
	<Relation name="Owner" act="set">
	</Relation>
</Asset>

How to Add and Remove Values from a Multi-Value Relation​

Updating a multi-value relation is accomplished by marking enclosed Asset elements with either act="add" or act="remove". This post will add one Member and remove another Member from the Scope with ID 0:

POST /VersionOne/rest-1.v1/Data/Scope/0 HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 197

<Asset>
	<Relation name="Members">
		<Asset idref="Member:1000" act="add"/>
		<Asset idref="Member:1001" act="remove"/>
	</Relation>
</Asset>

How to Create a New Asset​

Creating a new asset is accomplished by posting to the asset type URL (without an ID). This post will create a Story with the name "New Story", within the Scope with ID 0.

POST /VersionOne/rest-1.v1/Data/Story HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 221

<Asset>
	<Attribute name="Name" act="set">New Story</Attribute>
	<Relation name="Scope" act="set">
		<Asset idref="Scope:0" />
	</Relation>
</Asset>

The response is:

<Asset href="/VersionOne/rest-1.v1/Data/Story/1072/214" id="Story:1072:214">
	<Attribute name="Name">New Story</Attribute>
	<Relation name="Scope">
		<Asset href="/VersionOne.Web/rest-1.v1/Data/Scope/0" idref="Scope:0" />
	</Relation>
</Asset>
Remarks

When creating a new asset, all required attributes must be provided, or the save will fail. In the above example, the Name and Scope attributes are the minimum required attributes for a Story.