Overview

Deprecatation Warning

As part of the backward incompatibility introduced with Orchestrator version 10.0.0, API version 2 (v2) is deprecated from that version onwards. Not only is this version of the API deprecated, but also discovery of brownfield resources is no longer available.
We highly recommend that you start using API version 3 (v3),  which is mostly identical, as soon as possible.

IMCO API v2 is the Application Programming Interface you can use to interact programmatically with the IMCO platform from version 8.0.0 onwards. The API allows you to:

  • Retrieve, create, update and destroy your Templates, Cookbooks and Scripts (Blueprint namespace).
  • Retrieve, create, update and destroy your Firewall profiles, VPCs, subnets and VPNs (Network namespace).
  • Retrieve, create, update and destroy volumes and retrieve storage plans (Storage namespace). Available from version 8.2 onwards.
  • Retrieve, create, update and destroy SSH profiles (Cloud namespace).
  • Retrieve information about, commission, boot, reboot, execute scripts on, shutdown, override and decommission your server arrays and servers (Cloud namespace).
  • Retrieve cloud accounts and retrieve, create, update and destroy SaaS accounts (Settings namespace).
  • Retrieve events related to your customer on the platform (Audit namespace).

Contents

Using the API

IMCO API is an HTTPS REST API, which allows you to use tools such as curl to avoid complex coding.

As an example, you can use this to make a call to the ping resource:

(ca.crt, api.key and api.crt are respectively the CA certificate, the API private key and the API certificate of the customer)

curl --cacert ca.crt --key api.key --cert api.crt https://clients.<IMCO PLATFORM DOMAIN>/v2/ping

Authentication

IMCO API requests are secured by SSL both on the server's side (which ensures users connect to the actual server and avoids man-in-the-middle attacks) and on the client's side through the use of a user-specific SSL certificate signed by the IMCO service CA, which effectively authenticates the user before the service.

This means that in order to use the API, you must sign the requests you make with the IMCO API SSL certificate, which you can generate on the IMCO platform.

Format

Both request and response body parameters, when needed, must be or are specified in JSON. Thus, requests must specify an ‘application/json' Accept header if any at all, and both non-body-empty requests and responses shall contain the Content-Type header set to ‘application/json'.

HTTP methods

IMCO API, following REST conventions, makes use of the semantics of HTTP methods.

Therefore:

  • The GET method must be used to retrieve sets (listing) or individual elements (showing).
  • The POST method must be used to create new elements.
  • The PUT method must be used to update existing elements.
  • The DELETE method must be used to destroy elements. The method to use for each request is documented in the API requests below.