API Introduction

MNX.io Docs
Search…
MNX.io Documentation
Getting started
CloudAPI Documentation
Getting Started
RBAC: Users, Roles & Policies
Images
API Introduction
CloudAPI exposes a REST API over HTTPS. You can work with the REST API by either calling it directly via tooling you already know about (such as curl, et al), or by using the CloudAPI CLIs and SDKs from Joyent. The node-triton CloudAPI SDK & CLI is available as an npm module, which you can install with:
npm install triton
Alternatively, there is the more stable and feature-complete node-smartdc:
npm install smartdc
Although node-triton has fewer features -- for now -- it will continue to receive the most development effort and future support. node-smartdc is in maintenance.
The rest of this document will show all APIs in terms of both the raw HTTP specification, the CLI commands, and sometimes the node-smartdc SDK.
Issuing Requests
All HTTP calls to CloudAPI must be made over TLS, and requests must carry at least two headers (in addition to standard HTTP headers): Authorization and Api-Version. The details are explained below. In addition to these headers, any requests requiring content must be sent in an acceptable scheme to CloudAPI. Details are also below.
Content-Type
For requests requiring content, you can send parameters encoded with application/json, application/x-www-form-urlencoded or multipart/form-data. Joyent recommends application/json. The value of the Accept header determines the encoding of content returned in responses. CloudAPI supports application/json response encodings only.
For example, all of the following are valid calls:
Query String (on the uri):
POST /my/keys?name=rsa&key=... HTTP/1.1
Host: joyent.com
Authorization: ...
Content-Length: 0
Form encoded in the body:
POST /my/keys HTTP/1.1
Host: joyent.com
Authorization: ...
Content-Type: application/x-www-form-urlencoded
Content-Length: 123
​
name=rsa&key=...
JSON in the body:
POST /my/keys HTTP/1.1
Host: joyent.com
Authorization: ...
Content-Type: application/json
Content-Length: 123
​
{"name":"rsa","key":"..."}
Authorization
All API calls to CloudAPI require an Authorization header, which supports multiple "schemes". Currently CloudAPI supports only one Authentication mechanism due to PCI compliance restrictions:
HTTP Signature Authentication Scheme. This Scheme is outlined in Appendix B.
In order to leverage HTTP Signature Authentication, only RSA signing mechanisms are supported, and your keyId must be equal to the path returned from a ListKeys API call. For example, if your Triton login is demo, and you've uploaded an RSA SSH key with the name foo, an Authorization header would look like:
Authorization: Signature keyId=/demo/keys/foo,algorithm="rsa-sha256" ${Base64(sign($Date))}
The default value to sign for CloudAPI requests is simply the value of the HTTP Date header. For more information on the Date header value, see RFC 2616. All requests to CloudAPI using the Signature authentication scheme must send a Date header. Note that clock skew will be enforced to within 300 seconds (positive or negative) from the value sent.
Full support for the HTTP Signature Authentication scheme is provided in both CloudAPI SDKs; an additional reference implementation for Node.js is available in the npm http-signature module, which you can install with:
npm install http-signature
Using cURL with CloudAPI
Since cURL is commonly used to script requests to web services, here's a simple Bash function you can use to wrap cURL when communicating with CloudAPI:
function cloudapi() {
    local now=$(date -u '+%a, %d %h %Y %H:%M:%S GMT')
    local signature=$(echo -n "$now" | openssl dgst -sha256 -sign ~/.ssh/id_rsa | openssl enc -e -a | tr -d '\n')
    local url="$SDC_URL$1"
    shift
​
    curl -s -k -i \
        -H 'Accept: application/json' \
        -H "accept-version: ~8" \
        -H "Date: $now" \
        -H "Authorization: Signature keyId=\"/$SDC_ACCOUNT/keys/id_rsa\",algorithm=\"rsa-sha256\" $signature" \
        "[email protected]" "$url"
    echo
}
You may need to alter the path to your SSH key in the above function, as well as the path its public-key is saved under in Triton.
With that function, you could just do:
cloudapi /my/machines
CloudAPI HTTP Responses
CloudAPI returns all response objects as application/json encoded HTTP bodies. In addition to the JSON body, all responses have the following headers:
Header
Description
Date
When the response was sent (RFC 1123 format)
Api-Version
The exact version of the CloudAPI server you spoke with
Request-Id
A unique id for this request; you should log this
Response-Time
How long the server took to process your request (ms)
If there is content, you can expect:
Header
Description
Content-Length
How much content, in bytes
Content-Type
Formatting of the response (almost always application/json)
Content-MD5
An MD5 checksum of the response; you should check this
HTTP Status Codes
Your client should check for each of the following status codes from any API request:
Code
Description
Details
400
Bad Request
Invalid HTTP Request
401
Unauthorized
Either no Authorization header was sent, or invalid credentials were used
403
Forbidden
No permissions to the specified resource
404
Not Found
Resource was not found
405
Method Not Allowed
Method not supported for the given resource
406
Not Acceptable
Try sending a different Accept header
409
Conflict
Most likely invalid or missing parameters
413
Request Entity Too Large
You sent too much data
415
Unsupported Media Type
Request was encoded in a format CloudAPI does not understand
420
Slow Down
You're sending too many requests too quickly
449
Retry With
Invalid Version header; try with a different Api-Version string
500
Internal Error
An unexpected error occurred; see returned message for more details.
503
Service Unavailable
Either there's no capacity in this datacenter, or it's in a maintenance window
Error Responses
In the event of an error, CloudAPI will return a standard JSON error response object in the body with the scheme:
{
  "code": "CODE",
  "message": "human readable string"
}
Where the code element is one of:
Code
Description
BadRequest
You sent bad HTTP
InternalError
Something went wrong in Triton
InUseError
The object is in use and cannot be operated on
InvalidArgument
You sent bad arguments or a bad value for an argument
InvalidCredentials
Authentication failed
InvalidHeader
You sent a bad HTTP header
InvalidVersion
You sent a bad Api-Version string
MissingParameter
You didn't send a required parameter
NotAuthorized
You don't have access to the requested resource
RequestThrottled
You were throttled
RequestTooLarge
You sent too much request data
RequestMoved
HTTP Redirect
ResourceNotFound
What you asked for wasn't found
UnknownError
Something completely unexpected happened!
Clients are expected to check HTTP status code first, and if it's in the 4xx range, they can leverage the codes above.
RBAC: Users, Roles & Policies
API Details
Last modified 2yr ago
Copy link
On this page
Issuing Requests
CloudAPI HTTP Responses