Rancher API with proper Rest calls


I’m working on writing a ruby gem to interface with the Rancher API, it can be found here: https://github.com/jwhitcraft/rancher.rb I’ve recently noticed that Rancher doesn’t actually support what is considered peroper HTTP methods for Restful Services, eg using PUT for updates, DELETE for delets, POST for creating items and GET for fetching.

I’m just wondering if there are plans to support the full suite of HTTP Methods for Restful Services.

That is exactly how those things work. What might be confusing is that there are “create”, “update”, and “remove” actions listed but these are a side effect of the API framework that will eventually be removed. The correct way to invoke them is POST/PUT/DELETE

@vincent, thanks for pointing that out. It didn’t occur to me to test with the proper calls.

Thanks and keep up the awesome work!

Edit @vincent i just tried this on my test instance: DELETE http://docker.dev:8080/v1/projects/1a5/serviceConsumeMaps/1scm5/ and it returned 405 - Method not allowed I’m running v0.35.0.

Any idea?

Service relationships are manipulated with add/set/removeServiceLinks actions on the service. The maps are read-only. The schema for /v1[/projects/1a5]/schemas/serviceconsumemap resourceMethods and collectionMethods should only contain GET.

Since you’re building a client, a few notes…

  • Schemas contain info about everything. Every type, the input and output of actions, etc. Long and boring info in the spec.
  • It’s possible to make a completely generic client that just knows about schemas and generates classes, methods to call actions, etc from them.
    • This is how the python client works, along with the php one and others, but there’s not an existing open-source Ruby one that I know of.
    • This would be desirable because there will be additional separate APIs to talk to in the (not-so-distant) future and you can then use it for free. Also you don’t have to write out boilerplate code for 40 different types.
  • In general you shouldn’t hardcode/string concatenate anything to generate a URL.
    • There’s a X-Api-Schemas header in all responses, so any request to the root gives you the location of schemas, though hardcoding /v1/schemas is pretty safe.
    • From there the schemas tell you the URLs for collections of each type. Adding "/"+id to get an individual one is ok here, as we don’t provide a template or anything to give you that.
    • While we have no plans to actually change them, all other valid paths and URLs returned in the response should be considered arbitrary opaque strings. We make no guarantees that they will stay the same or maintain the same format, etc.
  • In particular, use the value from actions[action_name] to call the action, not hardcoded type/id?action=setservicelinks.
    • The presence of an action in that map, or lack thereof, tells you whether it’s allowed in the current state. You’ll get back an error if you try to call an action that wasn’t in there.
    • (except create, update, and remove, which are oddballs and you should pretend don’t exist because they will be removed someday).
1 Like


Thank you for the info Sir :beers: . I will dig into the Spec and also look over the two clients and rework how my client interfaces with the api.


Again thank you for the existing code. I’ve got the ruby version about 90% done with what is done in the Python and PHP version. I should have it completed this week sometime.


1 Like

@jwhitcraft is it in rubygems? I tried to install from there, no luck.

I have not published it yet as there are little to no tests, but I’m using it in production so i guess it’s safe to publish. I’ll do so when i get back home later today, and i’ll post back when it’s done.


I published the gem a little bit ago: https://rubygems.org/gems/rancher.rb

Cool. Thanks @jwhitcraft for helping.

Is it possible only to query, or can I also make changes? I have been looking for a way to upload a compose yml via the API (as if running rancher-compose).


by all means, submit a pull request.

Edit I just understood your message. I have not tested the ability to upload a a compose file or how even rancher-compose does this.

I’m sure it would be possible if you find the right api call, I can do some digging once i get back to work on Jan 4th.

I would love to submit PRs, but I am a bit overloaded. When I can, will get to it wherever I can help.

I asked a question in one of the there forum discussions, I assume everyone is out for Christmas/New Year’s. I just don’t know what the API call is.

And… Happy New Year!


I just saw your post and the reply to it pointing to the proper api.

I’ll add that example to the docs on the repo later today.


rancher-compose doesn’t use the fields I mentioned. It parses the yaml and makes the appropriate environment (stack) and service create calls. Using the {docker,rancher}Compose actually makes the API call rancher-compose to do the import.