When starting out with Cloud Foundry you are likely to use vmc for most of your communications with the cloud, but under the covers, vmc just fires off HTTP requests to the cloud controller REST interface.  This REST interface is completely legitimate for you to use, either “by hand” with something like curl, or from within your applications using an HTTP client.  As is the case with much of Cloud Foundry at the moment, documentation on this interface is somewhat (okay) completely lacking, so you have to be a bit creative in figuring it out.

I’ve just spent a few hours sorting through some of the idiosyncrasies of this Cloud Controller REST interface and here’s what I’ve learned.

• There are a couple of people who did start to document this interface as a community effort; it hasn’t been updated in some time but it seems to still be accurate.  It’s here.
• One of the best ways to figure out the REST resource is to run vmc with trace turned on.  There is a decent post on stackoverflow that describes this in a bit of detail.
  • One “gotcha” on this is that the trace doesn’t show you everything – in particular some of the details I list below.
• There are a handful of resources that do not require authentication.  Things like:
  • Info and the services and frameworks sub-resources; you can GET these resources at /info, /info/services and /info/runtimes, respectively.
  • User token:  By POSTing to the /users/{userid}/tokens you can get back the user token that is needed for many other resoruces.  For example, the following command will return my token.

    curl -X POST -d '{"password" : "mypassword" }' api.vcap.me/users/cornelia.davis@emc.com/tokens

    Note that this returns something of the form: “bearer …. and a whole bunch of characters ….” – the “bearer ” is part of the token.

• Notice that the POST to get the user token didn’t require any particular headers – this will change as we progress through some of the other requests.
• Now try doing a GET on /info, but with the header “Authorization” set to the user token.  You will notice that the json returned is slightly different, namely you will see that you are now authenticated.

  {
    "name": "vcap",
    "build": 2222,
    "support": "http://support.cloudfoundry.com",
    "version": "0.999",
    "description": "VMware's Cloud Application Platform",
    "allow_debug": false,
    "frameworks": [...snip...],
    "authorization_endpoint": "http://uaa.vcap.me",
    "user": "cornelia.davis@emc.com",
    "limits": {
      "memory": 2048,
      "app_uris": 4,
      "services": 16,
      "apps": 20
    },
    "usage": {
      "memory": 1792,
      "apps": 4,
      "services": 2
    }
  }

  Notice that no other headers need be set at this point – just the Authorization one.

• With the Authorization header set you can now GET a bunch of different resources (this is just a sampling):
  • GET /services
  • GET /apps
  • GET /apps/{appname}
  • GET /apps/{appname}/stats
  • GET /apps/{appname}/crashes
  • …
• As soon as you want to get more details on a particular service, however, you will need another header, or two.
  • Don’t ask me why – as I said some idiosyncrasies – but in the case of services there is this bit of code that I finally dug up in the cloud_controller/app/helpers/services_helper.rb file that validates that the content type header is set to JSON for services requests.  By the way, the error message that is returned if you don’t have this header is:

    {"code":100,"description":"Bad request"}

    So set the Content-type header to application/json and you will now be able to access the service offerings which you could not before.

    • GET or POST /services/v1/offerings: This gives you a list of the system services but with a bit more information than you get with /info/services.  In particular, you will get the URL for the service gateway.
  • And finally, there is a bit more of a drill down into the details of a particular service but in order to get there you need one more header: the service token.  This value is provided in the X-VCAP-Service-Token HTTP header and what the value is depends on how you’ve configured tokens for your service; in a BOSH deployment it is probably a part of your deployment manifest, in a vanilla vcap install, it is probably set in the cloud_controller.yml file.  So now you can access
    • GET /services/v1/offerings/{service-label}/handles: Note that this gives information about the service nodes, including things like the host IP address and the other things (credentials) returned by the service node.

  So my final curl in all it’s glory is:

  curl -H Authorization:bearer ...the rest of my token... -H Content-type:application/json
       -H X-VCAP-Service-Token:changeme api.vcap.me/services/v1/offerings/cassandra-1.0/handles