Skip to main content
System StatusContact Support
VersionOne Community

Creating a New Asset Using the API

Prerequisites

1. Understand the Asset Shape

Before we create a new asset, we need to understand the attributes and relationships for the asset type. Therefore we query meta.v1 to understand the shape of the asset. For example, if we want to create a new Story, we use the following query.

<Server Base URI>/meta.v1/Story?xsl=api.xsl

The result of this query will resemble the following.

Story derives from PrimaryWorkitem
  ID : Relation to Story
  * Scope : Relation to Scope — reciprocal of Workitems
  * Name : Text
  Description : LongText
  Order : Rank
  Status : Relation to StoryStatus — reciprocal of PrimaryWorkitems
  Owners : Multi-Relation to Member — reciprocal of OwnedWorkitems
  Super : Relation to Epic — reciprocal of Subs
  Parent : Relation to Theme — reciprocal of Children
  ChangeDate : Date
  CreateDate : Date
  ChangedBy : Relation to Member
  CreatedBy : Relation to Member

In context of creating a new asset, we inspect attributes definitions to understand required attributes. When using xsl=api.xsl parameter, the required attributes are marked with *. Therefore, in the above example, we know a Name and a Scope relationship are required for Story.

2. Request a New Asset Template

In order to create a new asset, we need to provide an XML body. To get a template of that XML body, we can use the rest-1.v1/New endpoint. For example, if we want to create a new Story in the root project, we can use the following query. (Remember to send the Authorization header for OAuth.)

<Server Base URI>/rest-1.v1/New/Story?ctx=Scope:0

The result of this query will resemble the following

<Asset href="/VersionOne/rest-1.v1/New/Story">
  <Relation name="Scope" act="set">
    <Asset href="/VersionOne/rest-1.oauth.v1/Data/Scope/0" idref="Scope:0"/>
  </Relation>
</Asset>

The results have been pre-populated based on the ctx parameter; however, the template does not attempt to pre-populate all required attributes. So we need to add the Name attribute as we learned from exploring the asset shape. The new Story should have at least the following.

<Asset href="/VersionOne/rest-1.v1/New/Story">
  <Attribute name="Name" act="set">Create a New Asset</Attribute>
  <Relation name="Scope" act="set">
    <Asset href="/VersionOne/rest-1.oauth.v1/Data/Scope/0" idref="Scope:0"/>
  </Relation>
</Asset>

3. Post the New Asset

In order to create a new asset, we need to send an HTTP POST to the rest-1.v1/Data endpoint. For example, we send the following to create a new Story(Remember to send the Authorization header for OAuth.)

POST /VersionOne/rest-1.v1/Data/Story HTTP/1.1
Host: www14.v1host.com
Content-Type: application/xml

<Asset href="/v1sdktesting/rest-1.v1/New/Story">
<Attribute name="Name" act="set">Create a New Asset</Attribute>
<Relation name="Scope" act="set">
<Asset href="/v1sdktesting/rest-1.v1/Data/Scope/0" idref="Scope:0" />
</Relation>
</Asset>

The result of this post will resemble the following.

<Asset href="/VersionOne/rest-1.v1/Data/Story/14191/21510" id="Story:14191:21510">
  <Attribute name="Name">Create a New Asset</Attribute>
  <Relation name="Scope">
    <Asset href="/VersionOne/rest-1.oauth.v1/Data/Scope/0" idref="Scope:0" />
  </Relation>
</Asset>

This result confirms the new asset was created. We can now access it as Story:14191. If we want to refer to the values at this starting state, we would use the moment, as in Story:14191:21510. The result also confirms the Name and Scope relationship that we set.

  • Was this article helpful?