README

Introduction Contabo API allows you to manage your resources using HTTP requests. This documentation includes a set of HTTP endpoints that are designed to RESTful principles. Each endpoint includes descriptions, request syntax, and examples. Contabo provides also a CLI tool which enables you to manage your resources easily from the command line. CLI Download and Installation instructions. ## Product documentation If you are looking for description about the products themselves and their usage in general or for specific purposes, please check the Contabo Product Documentation. ## Getting Started In order to use the Contabo API you will need the following credentials which are available from the Customer Control Panel: 1. ClientId 2. ClientSecret 3. API User (your email address to login to the Customer Control Panel) 4. API Password (this is a new password which you'll set or change in the Customer Control Panel) You can either use the API directly or by using the `cntb` CLI (Command Line Interface) tool. ### Using the API directly #### Via `curl` for Linux/Unix like systems This requires `curl` and `jq` in your shell (e.g. `bash`, `zsh`). Please replace the first four placeholders with actual values. sh CLIENT_ID=<ClientId from Customer Control Panel> CLIENT_SECRET=<ClientSecret from Customer Control Panel> API_USER=<API User from Customer Control Panel> API_PASSWORD='<API Password from Customer Control Panel>' ACCESS_TOKEN=$(curl -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\" --data-urlencode \"username=$API_USER\" --data-urlencode \"password=$API_PASSWORD\" -d 'grant_type=password' 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' | jq -r '.access_token') # get list of your instances curl -X GET -H \"Authorization: Bearer $ACCESS_TOKEN\" -H \"x-request-id: 51A87ECD-754E-4104-9C54-D01AD0F83406\" \"https://api.contabo.com/v1/compute/instances\" | jq #### Via `PowerShell` for Windows Please open `PowerShell` and execute the following code after replacing the first four placeholders with actual values. powershell $client_id='<ClientId from Customer Control Panel>' $client_secret='<ClientSecret from Customer Control Panel>' $api_user='<API User from Customer Control Panel>' $api_password='<API Password from Customer Control Panel>' $body = @{grant_type='password' client_id=$client_id client_secret=$client_secret username=$api_user password=$api_password} $response = Invoke-WebRequest -Uri 'https://auth.contabo.com/auth/realms/contabo/protocol/openid-connect/token' -Method 'POST' -Body $body $access_token = (ConvertFrom-Json $([String]::new($response.Content))).access_token # get list of your instances $headers = @{} $headers.Add(\"Authorization\",\"Bearer $access_token\") $headers.Add(\"x-request-id\",\"51A87ECD-754E-4104-9C54-D01AD0F83406\") Invoke-WebRequest -Uri 'https://api.contabo.com/v1/compute/instances' -Method 'GET' -Headers $headers ### Using the Contabo API via the `cntb` CLI tool 1. Download `cntb` for your operating system (MacOS, Windows and Linux supported) here 2. Unzip the downloaded file 3. You might move the executable to any location on your disk. You may update your `PATH` environment variable for easier invocation. 4. Configure it once to use your credentials `sh cntb config set-credentials --oauth2-clientid=<ClientId from Customer Control Panel> --oauth2-client-secret=<ClientSecret from Customer Control Panel> --oauth2-user=<API User from Customer Control Panel> --oauth2-password='<API Password from Customer Control Panel>'` 5. Use the CLI `sh # get list of your instances cntb get instances # help cntb help` ## API Overview ### Compute Management The Compute Management API allows you to manage compute resources (e.g. creation, deletion, starting, stopping) of VPS and VDS (please note that Storage VPS are not supported via API or CLI) as well as managing snapshots and custom images. It also offers you to take advantage of cloud-init at least on our default / standard images (for custom images you'll need to provide cloud-init support packages). The API offers provisioning of cloud-init scripts via the `user_data` field. Custom images must be provided in `.qcow2` or `.iso` format. This gives you even more flexibility for setting up your environment. ### Object Storage The Object Storage API allows you to order, upgrade, cancel and control the auto-scaling feature for S3 compatible object storage. You may also get some usage statistics. You can only buy one object storage per location. In case you need more storage space in a location you can purchase more space or enable the auto-scaling feature to purchase automatically more storage space up to the specified monthly limit. Please note that this is not the S3 compatible API. It is not documented here. The S3 compatible API needs to be used with the corresponding credentials, namely an `access_key` and `secret_key`. Those can be retrieved by invoking the User Management API. All purchased object storages in different locations share the same credentials. You are free to use S3 compatible tools like `aws` cli or similar. ### Private Networking The Private Networking API allows you to manage private networks / Virtual Private Clouds (VPC) for your Cloud VPS and VDS (please note that Storage VPS are not supported via API or CLI). Having a private network allows the associated instances to have a private and direct network connection. The traffic won't leave the data center and cannot be accessed by any other instance. With this feature you can create multi layer systems, e.g. having a database server being only accessible from your application servers in one private network and keep the database replication in a second, separate network. This increases the speed as the traffic is NOT routed to the internet and also security as the traffic is within it's own secured VLAN. Adding a Cloud VPS or VDS to a private network requires a reinstallation to make sure that all relevant parts for private networking are in place. When adding the same instance to another private network it will require a restart in order to make additional virtual network interface cards (NICs) available. Please note that for each instance being part of one or several private networks a payed add-on is required. You can automatically purchase it via the Compute Management API. ### Secrets Management You can optionally save your passwords or public ssh keys using the Secrets Management API. You are not required to use it there will be no functional disadvantages. By using that API you can easily reuse you public ssh keys when setting up different servers without the need to look them up every time. It can also be used to allow Contabo Supporters to access your machine without sending the passwords via potentially unsecure emails. ### User Management If you need to allow other persons or automation scripts to access specific API endpoints resp. resources the User Management API comes into play. With that API you are able to manage users having possibly restricted access. You are free to define those restrictions to fit your needs. So beside an arbitrary number of users you basically define any number of so called `roles`. Roles allows access and must be one of the following types: * `apiPermission` This allows you to specify a restriction to certain functions of an API by allowing control over POST (=Create), GET (=Read), PUT/PATCH (=Update) and DELETE (=Delete) methods for each API endpoint (URL) individually. * `resourcePermission` In order to restrict access to specific resources create a role with `resourcePermission` type by specifying any number of tags. These tags need to be assigned to resources for them to take effect. E.g. a tag could be assigned to several compute resources. So that a user with that role (and of course access to the API endpoints via `apiPermission` role type) could only access those compute resources. The `roles` are then assigned to a `user`. You can assign one or several roles regardless of the role's type. Of course you could also assign a user `admin` privileges without specifying any roles. ### Tag Management The Tag Management API allows you to manage your tags in order to organize your resources in a more convenient way. Simply assign a tag to resources like a compute resource to manage them.The assignments of tags to resources will also enable you to control access to these specific resources to users via the User Management API. For convenience reasons you might choose a color for tag. The Customer Control Panel will use that color to display the tags. ## Requests The Contabo API supports HTTP requests like mentioned below. Not every endpoint supports all methods. The allowed methods are listed within this documentation. Method | Description --- | --- GET | To retrieve information about a resource, use the GET method.
数据以JSON对象的形式返回。GET方法为只读，不会影响任何资源。POST | 发起POST方法创建新对象。在请求体中包含所有必要的属性，并编码为JSON。PATCH | 一些资源支持使用PATCH进行部分修改，
这会修改特定属性而不会更新整个对象表示。PUT | 使用PUT方法更新资源的信息。
PUT会设置项目的新值，而不管它们当前的值。
如果未找到，则操作将返回4xx错误和适当的消息。## 响应通常，Contabo API应响应用户请求。返回的数据以JSON格式提供，允许在任意编程语言或工具中轻松处理。与HTTP请求一样，您将获得所谓的HTTP状态码。以下表格列出了常见的HTTP状态码。请注意，端点和方法的描述并未详细列出所有可能的状态码，因为它们是通用的。仅列出具有相应响应数据的特殊返回代码。响应代码 | 描述 --- | --- 200 | 响应包含您请求的信息。 201 | 请求被接受。资源已创建。 204 | 请求成功，没有返回其他信息。 400 | 请求格式不正确。 401 | 您没有提供有效的认证凭据。 402 | 请求被拒绝，因为它需要额外的付费服务。 403 | 您无权执行请求。 404 | 请求的资源不存在或未找到结果。 409 | 资源冲突。例如，在尝试创建或更改资源时检测到违反唯一数据约束。 429 | 达到速率限制。请稍后再进行更多请求。 500 | 由于服务器端问题，我们无法执行请求。在这种情况下，请重试或联系支持。并非每个端点都返回数据。例如，DELETE请求通常不返回任何数据。所有其他都返回数据。为了便于处理，返回值由以下字段表示的元数据组成，例如 `_links` 或 `_pagination`。实际数据在名为 `data` 的字段中返回。为了方便起见，此 `data` 字段始终以数组的形式返回，即使它只包含一个单一元素。有关Contabo API的一些一般性信息，请参阅Contabo。

此PHP包由Swagger Codegen项目自动生成

API版本：1.0.0
构建包：io.swagger.codegen.v3.generators.php.PhpClientCodegen 更多信息，请访问https://contabo.com

要求

PHP 5.5及更高版本

安装与使用

Composer

要通过Composer安装绑定，请将以下内容添加到composer.json

{
  "repositories": [
    {
      "type": "git",
      "url": "https://github.com/git_user_id/git_repo_id.git"
    }
  ],
  "require": {
    "git_user_id/git_repo_id": "*@dev"
  }
}

然后运行composer install

手动安装

下载文件并包含autoload.php

    require_once('/path/to/SwaggerClient-php/vendor/autoload.php');

测试

要运行单元测试

composer install
./vendor/bin/phpunit

入门指南

请遵循安装步骤，然后运行以下操作

<?php
require_once(__DIR__ . '/vendor/autoload.php');


$apiInstance = new Contabo\ContaboSdk\Api\ImagesApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$body = new \Contabo\ContaboSdk\Model\CreateCustomImageRequest(); // \Contabo\ContaboSdk\Model\CreateCustomImageRequest | 
$x_request_id = "x_request_id_example"; // string | [Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) to generate them manually.
$x_trace_id = "x_trace_id_example"; // string | Identifier to trace group of requests.

try {
    $result = $apiInstance->createCustomImage($body, $x_request_id, $x_trace_id);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling ImagesApi->createCustomImage: ', $e->getMessage(), PHP_EOL;
}


$apiInstance = new Contabo\ContaboSdk\Api\ImagesApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$x_request_id = "x_request_id_example"; // string | [Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) to generate them manually.
$image_id = "image_id_example"; // string | The identifier of the image
$x_trace_id = "x_trace_id_example"; // string | Identifier to trace group of requests.

try {
    $apiInstance->deleteImage($x_request_id, $image_id, $x_trace_id);
} catch (Exception $e) {
    echo 'Exception when calling ImagesApi->deleteImage: ', $e->getMessage(), PHP_EOL;
}


$apiInstance = new Contabo\ContaboSdk\Api\ImagesApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$x_request_id = "x_request_id_example"; // string | [Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) to generate them manually.
$x_trace_id = "x_trace_id_example"; // string | Identifier to trace group of requests.

try {
    $result = $apiInstance->retrieveCustomImagesStats($x_request_id, $x_trace_id);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling ImagesApi->retrieveCustomImagesStats: ', $e->getMessage(), PHP_EOL;
}


$apiInstance = new Contabo\ContaboSdk\Api\ImagesApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$x_request_id = "x_request_id_example"; // string | [Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) to generate them manually.
$image_id = "image_id_example"; // string | The identifier of the image
$x_trace_id = "x_trace_id_example"; // string | Identifier to trace group of requests.

try {
    $result = $apiInstance->retrieveImage($x_request_id, $image_id, $x_trace_id);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling ImagesApi->retrieveImage: ', $e->getMessage(), PHP_EOL;
}


$apiInstance = new Contabo\ContaboSdk\Api\ImagesApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$x_request_id = "x_request_id_example"; // string | [Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) to generate them manually.
$x_trace_id = "x_trace_id_example"; // string | Identifier to trace group of requests.
$page = 789; // int | Number of page to be fetched.
$size = 789; // int | Number of elements per page.
$order_by = array("order_by_example"); // string[] | Specify fields and ordering (ASC for ascending, DESC for descending) in following format `field:ASC|DESC`.
$name = "name_example"; // string | The name of the image
$standard_image = true; // bool | Flag indicating that image is either a standard (true) or a custom image (false)

try {
    $result = $apiInstance->retrieveImageList($x_request_id, $x_trace_id, $page, $size, $order_by, $name, $standard_image);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling ImagesApi->retrieveImageList: ', $e->getMessage(), PHP_EOL;
}


$apiInstance = new Contabo\ContaboSdk\Api\ImagesApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$body = new \Contabo\ContaboSdk\Model\UpdateCustomImageRequest(); // \Contabo\ContaboSdk\Model\UpdateCustomImageRequest | 
$x_request_id = "x_request_id_example"; // string | [Uuid4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) to identify individual requests for support cases. You can use [uuidgenerator](https://www.uuidgenerator.net/version4) to generate them manually.
$image_id = "image_id_example"; // string | The identifier of the image
$x_trace_id = "x_trace_id_example"; // string | Identifier to trace group of requests.

try {
    $result = $apiInstance->updateImage($body, $x_request_id, $image_id, $x_trace_id);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling ImagesApi->updateImage: ', $e->getMessage(), PHP_EOL;
}
?>

API端点文档

所有URI都是相对于https://api.contabo.com

模型文档

授权说明文档

bearer

类型：HTTP载体身份验证

作者

support@contabo.com

contabo / contabo-sdk

维护者

详细信息

README

要求

安装与使用

Composer

手动安装

测试

入门指南

API端点文档

模型文档

授权说明文档

bearer

作者