How to modify machine environments and roles through api

I have a node.js application that uses the octopus API. I’m trying to modify the environments bound to a machine and the machines role. I have the machines id and the id of the environment i wish to bind it to. However looking through the API documentation its unclear how to actually do this.

I’ve tried PUT’ing http://{ip}/api/machines/{id} and providing it the environments i wish to change but i get a 405 status back. However the user im trying to perform this under is an administrator.

I used fiddler performing the same action through the GUI and found the portal actually performs a post not put which according to the documentation creates a new machine. I tried to replicate this using the same data from fiddler and get an error back asking for an environment id, name, roles and thumbprint.

Could someone tell me how exactly to format the properties to perform this task and what properties are actually needed? I would have thought it would just be the id of the machine, environment id and roles but according to fiddler the portal is sending everything about the machine back to perform the same task.

Thanks all Stephen

I think I was being a bit very stupid, i forgot to add the header Content-Type application/json.

Now when i send the following in the body of my request it removes the errors asking for the required vaiables.

{"Name" : "vm_test_01","Thumbprint" : "38E000A5EA64A731F3C04ABDE81942D6B8A2948C","EnvironmentIds":["environments-2"],"Roles": ["local_db","local_web","upgrade_db","upgrade_web"]}

However now I get a new error:

{ "ErrorMessage": "This operation is not supported for a relative URI.", "FullException": "System.InvalidOperationException: This operation is not supported for a relative URI.\r\n at System.Uri.get_Scheme()\r\n at ...

Yet im using the URL specified by the documentation: http://{ip}/api/machines/{id}


I believe i may have solved the issue but this leads me to yet another question.

It was the Uri parameter.

If i pull the entire json object regarding the machine i am trying to update then put that in the body of my PUT request it works and i can modify values to update the machine.

So i followed it backwards removing properties from the object and the ‘uri’ property caused the relative url error above if not provided in the body of the PUT request. This property is not mentioned as a required variable in the documentation for this route, nor are some others that return an ‘please provide’ error.

However this leads me onto another question. I noticed the property, Squid is ‘nulled’ if i hit the PUT url with just ,name, thumbprint, uri, environmentIds and roles properties in the body of the request. What is this property used for? Should i be providing a value for it also as again it is not mentioned in the documentation for this route. I noticed that if i perform the same action through the GUI it is not 'nulled;. Why is this? Are other values ‘nulled’ if not provided? Surley the PUT route will only change the values provided?

Thanks again.


Thanks for getting in touch, and sorry for the delayed reply!

When using the API, Octopus expects entire resources to be PUT back (not just fields you want to change). The usual pattern would be to GET the machine, make the change, then PUT the whole machine back. For example, if you do a GET and you get:

{ Name: "Foo", Description: "Bar", ... }

And you PUT just this:

{ Name: "Foo" }

It doesn’t mean “don’t change the Description”, it means “there is no description”, so it will be set to the default value which is null. I understand this might not be consistent will all REST API’s nor intuitive, but it’s unfortunately how our API expects to work.

The SQUID property can be null when you PUT it, it’s used to track an internal ID of the Tentacle, but if you set it to null it will cause some issues - Octopus will have to re-discover the machine again, which takes time and may break any running deployments.

Hope that helps!



My apologies also for such a late reply, that means Octopus is great and working without issue :slight_smile:

That process makes perfect sense thanks. Also with the SQUID i just send back what i receive.