How can I update a VersionOne asset using JSON and the rest-1.v1 API endpoint?

Question

The default format for GET and POST operations against rest-1.v1/Data and similar endpoints in VersionOne is XML.

Can I GET or POST updates of an Asset using JSON instead?

Answer 1

Yes, can use JSON, with a couple of tweaks, and this caveat: this feature is not officially documented or supported, so it's subject to changes at any time in new releases.

To try the following examples, use admin / admin for the credentials.

How to GET an Asset as JSON

There are two ways to tell VersionOne to send you back JSON.

Method 1: Using an accept=application/json URL parameter

https://www14.v1host.com/v1sdktesting/rest-1.v1/Data/Issue/79242?accept=application/json&sel=Name,Description

The URL parameter accept=application/json tells VersionOne to send back JSON instead of XML for the selected Name and Description attributes for the specified Issue Asset.

Method 2: Using an Accept: application/json HTTP header

You can also use the standard Accept: application/json header. You can try this out on the http.html page that's included with any VersionOne instance:

1. Open https://www14.v1host.com/v1sdktesting/http.html
2. URL field: rest-1.v1/Data/Issue/79242?sel=Name,Description
3. Accept field: application/json
4. Press the GET button

The raw HTTP format of this query should look something like this:

GET /v1sdktesting/rest-1.v1/Data/Issue/79242?sel=Name,Description HTTP/1.1
Host: www14.v1host.com
Connection: keep-alive
Accept: application/json

You should get back a result like:

200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
VersionOne: Ultimate/16.0.3.233; Scrum
Content-Length: 252

{ "_type": "Asset", "href": "/v1sdktesting/rest-1.v1/Data/Issue/79242", "id": "Issue:79242", "Attributes": { "Name": { "_type": "Attribute", "name": "Name", "value": "Adam Martin" }, "Description": { "_type": "Attribute", "name": "Description", "value": "Adam's description" } } }

How to POST (update) an Asset using JSON

To update an attribute for an Asset using JSON instead of XML, you add a Content-Type: application/json header to your HTTP request, and use the required JSON format.

Here's an example of modifying the same Asset from above:

1. Open https://www14.v1host.com/v1sdktesting/http.html
2. URL field: rest-1.v1/Data/Issue/79242?sel=Name,Description
3. Accept field: application/json
4. Content-Type field: application/json
5. Payload field:

   { 
       "Attributes": {
           "Description": {
               "value": "New value from the internet",
               "act": "set"
           }
       }
   }
   

6. Press the POST button

You should get back a result like:

200 OK
Content-Type: application/json; charset=utf-8
VersionOne: Ultimate/16.0.3.233; Scrum
Content-Length: 210

{ "_type": "Asset", "href": "/v1sdktesting/rest-1.v1/Data/Issue/79242/114699", "id": "Issue:79242:114699", "Attributes": { "Description": { "_type": "Attribute", "name": "Description", "value": "New value from the internet" } } }

Using cURL from the command line

If you have cURL installed, you can test this with this command:

curl -i -X POST \
   -H "Authorization:Basic YWRtaW46YWRtaW4=" \
   -H "Accept:application/json" \
   -H "Content-Type:application/json" \
   -d \
'{ 
  "Attributes": {
    "Description": {
      "value": "Newer value from the internet",
      "act": "set"
    }
  }
}' \
 'https://www14.v1host.com/v1sdktesting/rest-1.v1/Data/Issue/79242?sel=Name%2CDescription'

Important notes

• The resulting body that comes back will be formatted according to the value of the Accept: header, so you could actually get back XML if you really wanted by changing that!
• The body that comes back does not match the attributes in the ?sel=Name,Description URL, but rather only the attributes that you actually modified in your POST.
• Be sure you specify the "act": "set" property in the attribute and not just the "value": "some new value...". If you fail to do this, you will still get back a 200 result, but you will not see the values you modified.

Answer 2

May be worth noting that when issuing an HTTP POST, with the Content-Type Header set to application/json, to the rest-1.v1/ endpoint and attempting to update a multi-value relation the following format is used:
<versionone-url>/rest-1.v1/Story
{ "Attributes": { "ChangeSets": { "name": "ChangeSets", "value": [ { "idref": "ChangeSet:1234", "act": "add" }, { "idref": "ChangeSet:3456", "act": "add" } ] } } }