Shelf Cloud EC2 API Reference
Objective
Section titled “Objective”The Shelf Cloud EC2 API creates and manages virtual servers, their storage and their access keys. It implements the Amazon EC2 query API, so that clients written for Amazon EC2 work against it with only an endpoint change.
Read this reference to call the API directly, or to understand exactly what your SDK is sending.
Requirements
Section titled “Requirements”- A Shelf Cloud account
- An access key id and secret access key
Instructions
Section titled “Instructions”Endpoint
Section titled “Endpoint”https://ec2.hel1.shelfcloud.comOne host per service per region. The service name and the region are part of every signature, so a client cannot be redirected to a differently-shaped host without every signature failing.
OPEN (Michael): the public API domain.
Protocol
Section titled “Protocol”The EC2 query protocol. Parameters are sent as application/x-www-form-urlencoded
in the body of a POST, or as a query string on a GET. Responses are XML.
This is not a design choice we are free to revisit: it is what the AWS SDKs send, and matching it byte for byte is the entire reason existing tooling works.
API version
Section titled “API version”Version=2016-11-15Every request carries the version. The SDKs supply it from their own service model; you do not set it by hand.
Versions earlier than the implemented one are accepted, so that an older but
still-supported SDK release continues to work. A version later than the
implemented one is rejected with InvalidParameterValue.
Authentication
Section titled “Authentication”Every request is signed with AWS Signature Version 4. See the authentication conventions.
The signing name for this service is ec2, and the signing region is the
region in the endpoint host.
Request ids
Section titled “Request ids”Every response carries the request id in three places, because different clients look in different ones:
- the
x-amzn-RequestIdresponse header, which every AWS SDK reads - a
<requestId>element in the body of a successful response - a
<RequestID>element in the body of an error response
The casing difference between the two body elements is inherited from Amazon EC2 and is preserved deliberately: a client that parses one and not the other must behave here exactly as it does there.
Quote the request id in any support case.
Reading an action page
Section titled “Reading an action page”Each action page states:
- what the action does, and what it changes
- every request parameter, its type, and whether it is required
- every response element
- the errors the action can return, and what causes each
- a worked example, as a signed request and its response
Where an action is not idempotent, the page says so and says what a retry does.
What is on the shelf
Section titled “What is on the shelf”| Instance types | Every shape we sell, and its AWS alias |
| Machine images | The OS shelf, and the login user for each |
| Volume types | What the disk underneath a volume actually is |
| Networking | Default VPC, security groups, the shared guest network |
| How prices are set | The rule every price is computed from |
| Service endpoints | Every hostname this cloud publishes |