There are many ways to create virtual machines in Azure. Of course the Azure Portal is the easiest but it is completely manual. When you have a lot of virtual machines that are part of your solution then you definitely want to script that process. When you script your Azure deployment you can do it with PowerShell or directly against the REST API. There are many examples on the web that provide PowerShell examples. However, I have not found a lot of material around the REST API.
So if you are trying to use the REST API, here are a couple of findings that I have run into that I hope will help you.
Which one should you utilize? If you are creating only one virtual machine you can create it with either API.
However, the issues start to arise when you need to create multiple virtual machines in the same script. If you use the Add Role API you will be able to create the first virtual machine but when the second virtual machine in the script is encountered you will receive a 400 Bad Request error (keep in mind that there are a number of 400 error codes that can be returned so make sure to look at the text and not just the HTTP status code). You can find all the Error codes here.
When you have multiple virtual machines to create in the script then you will need to start with the Create Virtual Machine Deployment API to create the first virtual machine and then use the Add Role API to create all subsequent virtual machines in your deployment.
You will notice when you look at the XML payload you need to include in the API call that the Create Virtual Machine Deployment contains a <Role> element within a <Deployment> element. When you look at the Add Role XML everything falls under the <PersistVMRole> element. So you need to run the API the does the <Deployment> first before running the <PersistVMRole> elements.
NOTE: It is very important that you have all the XML nodes in the correct order.
This is important because if the elements are not in the correct order, your VM can still be created (usually) but things like the Availability Set or EndPoints won't get created. What I have found is that when everything is in the right order (based on the examples in the documentation) then everything worked and all the virtual machines were created as expected.
In addition, if simple things like the <Protocol> node is before the <LoadBalancerProbe> element (in the documentation it is the only element after the <LoadBalancerProbe> element) then the endpoints will be created but the Load Balancer won't and you will see that the Load Balancer Set Name column in the portal will show an error stating Missing Probe.