Skip to content
/ contabo-php-client Public

Just an OpenAPI Generator Project for the Contabo API

2 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

petzsch/contabo-php-client

BranchesTags

Repository files navigation

OpenAPIClient-php

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.

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.

$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

    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

    # 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.
The data is returned as a JSON object. GET methods are read-only and do not affect any resources.
POST Issue a POST method to create a new object. Include all needed attributes in the request body encoded as JSON.
PATCH Some resources support partial modification with PATCH,
which modifies specific attributes without updating the entire object representation.
PUT Use the PUT method to update information about a resource.
PUT will set new values on the item without regard to their current values.
DELETE Use the DELETE method to destroy a resource in your account.
If it is not found, the operation will return a 4xx error and an appropriate message.

Responses

Usually the Contabo API should respond to your requests. The data returned is in JSON format allowing easy processing in any programming language or tools.

As common for HTTP requests you will get back a so called HTTP status code. This gives you overall information about success or error. The following table lists common HTTP status codes.

Please note that the description of the endpoints and methods are not listing all possibly status codes in detail as they are generic. Only special return codes with their resp. response data are explicitly listed.

Response Code Description
200 The response contains your requested information.
201 Your request was accepted. The resource was created.
204 Your request succeeded, there is no additional information returned.
400 Your request was malformed.
401 You did not supply valid authentication credentials.
402 Request refused as it requires additional payed service.
403 You are not allowed to perform the request.
404 No results were found for your request or resource does not exist.
409 Conflict with resources. For example violation of unique data constraints detected when trying to create or change resources.
429 Rate-limit reached. Please wait for some time before doing more requests.
500 We were unable to perform the request due to server-side problems. In such cases please retry or contact the support.

Not every endpoint returns data. For example DELETE requests usually don't return any data. All others do return data. For easy handling the return values consists of metadata denoted with and underscore ("_") like _links or _pagination. The actual data is returned in a field called data. For convenience reasons this data field is always returned as an array even if it consists of only one single element.

Some general details about Contabo API from Contabo.

For more information, please visit https://contabo.com.

Installation & Usage

Requirements

PHP 7.4 and later. Should also work with PHP 8.0.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/petzsch/contabo-php-client.git"
    }
  ],
  "require": {
    "petzsch/contabo-php-client": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

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



// Configure Bearer (JWT) authorization: bearer
$config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new OpenAPI\Client\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 = 04e0f898-37b4-48bc-a794-1a57abe6aa31; // 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.
$create_custom_image_request = new \OpenAPI\Client\Model\CreateCustomImageRequest(); // \OpenAPI\Client\Model\CreateCustomImageRequest
$x_trace_id = 'x_trace_id_example'; // string | Identifier to trace group of requests.

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

API Endpoints

All URIs are relative to https://api.contabo.com

Class Method HTTP request Description
ImagesApi createCustomImage POST /v1/compute/images Provide a custom image
ImagesApi deleteImage DELETE /v1/compute/images/{imageId} Delete an uploaded custom image by its id
ImagesApi retrieveCustomImagesStats GET /v1/compute/images/stats List statistics regarding the customer's custom images
ImagesApi retrieveImage GET /v1/compute/images/{imageId} Get details about a specific image by its id
ImagesApi retrieveImageList GET /v1/compute/images List available standard and custom images
ImagesApi updateImage PATCH /v1/compute/images/{imageId} Update custom image name by its id
ImagesAuditsApi retrieveImageAuditsList GET /v1/compute/images/audits List history about your custom images (audit)
InstanceActionsApi rescue POST /v1/compute/instances/{instanceId}/actions/rescue Rescue a compute instance / resource identified by its id
InstanceActionsApi resetPasswordAction POST /v1/compute/instances/{instanceId}/actions/resetPassword Reset password for a compute instance / resource referenced by an id
InstanceActionsApi restart POST /v1/compute/instances/{instanceId}/actions/restart Restart a compute instance / resource identified by its id.
InstanceActionsApi shutdown POST /v1/compute/instances/{instanceId}/actions/shutdown Shutdown compute instance / resource by its id
InstanceActionsApi start POST /v1/compute/instances/{instanceId}/actions/start Start a compute instance / resource identified by its id
InstanceActionsApi stop POST /v1/compute/instances/{instanceId}/actions/stop Stop compute instance / resource by its id
InstanceActionsAuditsApi retrieveInstancesActionsAuditsList GET /v1/compute/instances/actions/audits List history about your actions (audit) triggered via the API
InstancesApi cancelInstance POST /v1/compute/instances/{instanceId}/cancel Cancel specific instance by id
InstancesApi createInstance POST /v1/compute/instances Create a new instance
InstancesApi patchInstance PATCH /v1/compute/instances/{instanceId} Update specific instance
InstancesApi reinstallInstance PUT /v1/compute/instances/{instanceId} Reinstall specific instance
InstancesApi retrieveInstance GET /v1/compute/instances/{instanceId} Get specific instance by id
InstancesApi retrieveInstancesList GET /v1/compute/instances List instances
InstancesApi upgradeInstance POST /v1/compute/instances/{instanceId}/upgrade Upgrading instance capabilities
InstancesAuditsApi retrieveInstancesAuditsList GET /v1/compute/instances/audits List history about your instances (audit)
InternalApi createTicket POST /v1/create-ticket Create a new support ticket
InternalApi retrieveUserIsPasswordSet GET /v1/users/is-password-set Get user is password set status
ObjectStoragesApi cancelObjectStorage PATCH /v1/object-storages/{objectStorageId}/cancel Cancels the specified object storage at the next possible date
ObjectStoragesApi createObjectStorage POST /v1/object-storages Create a new object storage
ObjectStoragesApi retrieveDataCenterList GET /v1/data-centers List data centers
ObjectStoragesApi retrieveObjectStorage GET /v1/object-storages/{objectStorageId} Get specific object storage by its id
ObjectStoragesApi retrieveObjectStorageList GET /v1/object-storages List all your object storages
ObjectStoragesApi retrieveObjectStoragesStats GET /v1/object-storages/{objectStorageId}/stats List usage statistics about the specified object storage
ObjectStoragesApi updateObjectStorage PATCH /v1/object-storages/{objectStorageId} Modifies the display name of object storage
ObjectStoragesApi upgradeObjectStorage POST /v1/object-storages/{objectStorageId}/resize Upgrade object storage size resp. update autoscaling settings.
ObjectStoragesAuditsApi retrieveObjectStorageAuditsList GET /v1/object-storages/audits List history about your object storages (audit)
PrivateNetworksApi assignInstancePrivateNetwork POST /v1/private-networks/{privateNetworkId}/instances/{instanceId} Add instance to a Private Network
PrivateNetworksApi createPrivateNetwork POST /v1/private-networks Create a new Private Network
PrivateNetworksApi deletePrivateNetwork DELETE /v1/private-networks/{privateNetworkId} Delete existing Private Network by id
PrivateNetworksApi patchPrivateNetwork PATCH /v1/private-networks/{privateNetworkId} Update a Private Network by id
PrivateNetworksApi retrievePrivateNetwork GET /v1/private-networks/{privateNetworkId} Get specific Private Network by id
PrivateNetworksApi retrievePrivateNetworkList GET /v1/private-networks List Private Networks
PrivateNetworksApi unassignInstancePrivateNetwork DELETE /v1/private-networks/{privateNetworkId}/instances/{instanceId} Remove instance from a Private Network
PrivateNetworksAuditsApi retrievePrivateNetworkAuditsList GET /v1/private-networks/audits List history about your Private Networks (audit)
RolesApi createRole POST /v1/roles Create a new role
RolesApi deleteRole DELETE /v1/roles/{roleId} Delete existing role by id
RolesApi retrieveApiPermissionsList GET /v1/roles/api-permissions List of API permissions
RolesApi retrieveRole GET /v1/roles/{roleId} Get specific role by id
RolesApi retrieveRoleList GET /v1/roles List roles
RolesApi updateRole PUT /v1/roles/{roleId} Update specific role by id
RolesAuditsApi retrieveRoleAuditsList GET /v1/roles/audits List history about your roles (audit)
SecretsApi createSecret POST /v1/secrets Create a new secret
SecretsApi deleteSecret DELETE /v1/secrets/{secretId} Delete existing secret by id
SecretsApi retrieveSecret GET /v1/secrets/{secretId} Get specific secret by id
SecretsApi retrieveSecretList GET /v1/secrets List secrets
SecretsApi updateSecret PATCH /v1/secrets/{secretId} Update specific secret by id
SecretsAuditsApi retrieveSecretAuditsList GET /v1/secrets/audits List history about your secrets (audit)
SnapshotsApi createSnapshot POST /v1/compute/instances/{instanceId}/snapshots Create a new instance snapshot
SnapshotsApi deleteSnapshot DELETE /v1/compute/instances/{instanceId}/snapshots/{snapshotId} Delete existing snapshot by id
SnapshotsApi retrieveSnapshot GET /v1/compute/instances/{instanceId}/snapshots/{snapshotId} Retrieve a specific snapshot by id
SnapshotsApi retrieveSnapshotList GET /v1/compute/instances/{instanceId}/snapshots List snapshots
SnapshotsApi rollbackSnapshot POST /v1/compute/instances/{instanceId}/snapshots/{snapshotId}/rollback Revert the instance to a particular snapshot based on its identifier
SnapshotsApi updateSnapshot PATCH /v1/compute/instances/{instanceId}/snapshots/{snapshotId} Update specific snapshot by id
SnapshotsAuditsApi retrieveSnapshotsAuditsList GET /v1/compute/snapshots/audits List history about your snapshots (audit) triggered via the API
TagAssignmentsApi createAssignment POST /v1/tags/{tagId}/assignments/{resourceType}/{resourceId} Create a new assignment for the tag
TagAssignmentsApi deleteAssignment DELETE /v1/tags/{tagId}/assignments/{resourceType}/{resourceId} Delete existing tag assignment
TagAssignmentsApi retrieveAssignment GET /v1/tags/{tagId}/assignments/{resourceType}/{resourceId} Get specific assignment for the tag
TagAssignmentsApi retrieveAssignmentList GET /v1/tags/{tagId}/assignments List tag assignments
TagAssignmentsAuditsApi retrieveAssignmentsAuditsList GET /v1/tags/assignments/audits List history about your assignments (audit)
TagsApi createTag POST /v1/tags Create a new tag
TagsApi deleteTag DELETE /v1/tags/{tagId} Delete existing tag by id
TagsApi retrieveTag GET /v1/tags/{tagId} Get specific tag by id
TagsApi retrieveTagList GET /v1/tags List tags
TagsApi updateTag PATCH /v1/tags/{tagId} Update specific tag by id
TagsAuditsApi retrieveTagAuditsList GET /v1/tags/audits List history about your assignments (audit)
UsersApi createUser POST /v1/users Create a new user
UsersApi deleteUser DELETE /v1/users/{userId} Delete existing user by id
UsersApi generateClientSecret PUT /v1/users/client/secret Generate new client secret
UsersApi getObjectStorageCredentials GET /v1/users/{userId}/object-storages/{objectStorageId}/credentials/{credentialId} Get S3 compatible object storage credentials.
UsersApi listObjectStorageCredentials GET /v1/users/{userId}/object-storages/credentials Get list of S3 compatible object storage credentials for user.
UsersApi regenerateObjectStorageCredentials PATCH /v1/users/{userId}/object-storages/{objectStorageId}/credentials/{credentialId} Regenerates secret key of specified user for the S3 compatible object storages.
UsersApi resendEmailVerification POST /v1/users/{userId}/resend-email-verification Resend email verification
UsersApi resetPassword POST /v1/users/{userId}/reset-password Send reset password email
UsersApi retrieveUser GET /v1/users/{userId} Get specific user by id
UsersApi retrieveUserClient GET /v1/users/client Get client
UsersApi retrieveUserList GET /v1/users List users
UsersApi updateUser PATCH /v1/users/{userId} Update specific user by id
UsersAuditsApi retrieveUserAuditsList GET /v1/users/audits List history about your users (audit)

Models

Authorization

Authentication schemes defined for the API:

bearer

  • Type: Bearer authentication (JWT)

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

[email protected]

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

  • API version: 1.0.0
    • Generator version: 7.5.0
  • Build package: org.openapitools.codegen.languages.PhpClientCodegen

About

Just an OpenAPI Generator Project for the Contabo API

Resources

Readme
Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages