Trigger TFS Release Management with Artifact Version Number - tfs

Question

I am excited to see TFS Update 2 available for on premise and including the Release Management Feature part of the web experience. We have been waiting for this.
I need some help on how best to trigger the release.
A release can be triggered in 3 ways:
Continuous Deployment Trigger based on linking to TFS Build Definition
Manually
REST API
This is great but I don't think it fits what I would expect. I need help in a technical solve or in how I think about the problem.
My Thinking:
I believe the Build should create an artifact and put the artifact in a Drop location to be released now or a year from now. (need to rebuild or add a server later)
I feel the continuous deployment trigger breaks down as it depends on the artifact being in the TFS Build and the TFS Build will be deleted depending on your settings.
Possible Solution:
I believe the solution I need is to create a draft release using the REST Api and then pass in the path to the artifact in the drop location. In my case I would simply provide a version number and build the path inside the release.
Problem:
At this point the REST api is not documented.
I appreciate your thoughts on my thinking. It could be that I'm thinking about the problem in the wrong way.
Also, If anyone knows how to create a release using the REST api that would likely get me to where I need to be.
I see the REST api is to be documented at the following spot but is is not yet. I really want to get going, I have over 100 apps to deploy.
https://msdn.microsoft.com/en-us/library/vs/alm/release/managing-releases/create-release#CreateareleasebyusingtheRESTAPI

Answer 1

We also use TFS 2015 update 2 on-prem and use PowerShell to interface with TFS REST API.
As stated in comments on this thread the REST API documentation is live and to create a release refer to the following link: https://www.visualstudio.com/en-us/docs/integrate/api/rm/releases#create-a-release
To answer your question: - to create a release using a PowerShell script try the following:
$filePath = "C:\PATH_TO_JSON"
$username = 'DOMAIN\USRNAME'
$password = 'PASSWORD'
$body = Get-Content $filePath
$resource = "http://TFS_URL/_apis/release/releases`?api-version=2.2-preview.1"
$cred = New-Object System.Management.Automation.PSCredential($username, (ConvertTo-SecureString -String $password -AsPlainText -Force))
Invoke-RestMethod -Method Post -Uri "$resource" -Credential $cred -ContentType "application/json" -Body $body
The $filePath variable should point to a file containing the following JSON markup. Be sure to alter the variables within the example JSON to fit your on-prem Release Definition:
{
"definitionId": 12,
"description": "M 98 release",
"artifacts": [
{
"alias": "Fabrikam.CI",
"instanceReference": {
"id": "90"
}
}
]
}
You could also use JavaScript to interface with TFS REST API. See the post by #Elmar here: TFS 2015 REST API Authentication

Answer 2

The Release Management API docs for VSTS are live here. Most of the APIs should work for TFS 2015.2 also.
For creating a new release, refer to my earlier answer for the same.

Answer 3

You can retain a build indefinitely so it will always be available when you need it.

Answer 4

ReleaseManagement REST API got public at
https://www.visualstudio.com/integrate/api/rm/releases#Createarelease. Please have a look. While creating the release pass three things in the artifact :- alias, instanceReference (name and Id).