api.combahton.net – V2

Our API provides a flexible, extensible interface for automating common tasks within your own application. Currently, we accept only data sent in JSON format. You can use for example curl to send your requests.

API Schema

Our API is based on the following schema:

  • component
    • method
      • action
        • custom data

Authentication

Authentication is done by using a combination of your customer accounts email address and api key. The api key has a minimum length of 32 characters, defined previously in your customer accounts settings. A request could look like the following, authenticating yourself against the API:

curl -s --header "Content-Type: application/json" --request POST https://api.combahton.net/v2 --data '{"email":"user@example.net",
"secret":"XXX"}'

If the authentication was successful, you will not receive any sort of status. If the authentication fails, you will receive { „status“:„auth_failed“ }. In case your JSON Data does not provide sufficient details, required for authentication, you will receive { „status“:„auth_params_undefined“ }.

Available components

Currently, the following api components are available:

  • customer → Everything related to your customer account and contracts
  • antiddos → Anti-DDoS related calls (e.g. switch mitigation permanently on)
  • kvm → KVM Instance related calls (control, vnc, reinstall, etc.)

A component is defined like the following:

curl -s --header "Content-Type: application/json" --request POST https://api.combahton.net/v2 --data '{"email":"user@example.net",
"secret":"XXX",
"component":"customer"}'

This call will do nothing, you need to define a method and action too, like:

{ "email":"user@example.net",
"secret":"XXX",
"component":"customer",
"method":"credits",
"action":"view" }

Component: customer

The customer component currently offers the following methods:

  • method: credits
    • action: view → You will receive your account credit as integer
  • method: invoices
    • action: view_all - Returns a list of the last 100 invoices
    • action: view_unpaid - Returns a list of unpaid invoices
    • action: view
      • id: INVOICEID - Retrieve invoice as PDF file

For example, the following call will save invoice id 123 as invoice.pdf in your current directory:

curl -s --header "Content-Type: application/json" --request POST –data '{ "email":"user@example.net",
"secret":"XXX",
"component":"customer",
"method":"invoices",
"action":"view",
"id":"123" }' https://api.combahton.net/v2 -o invoice.pdf
  • method: contract
    • action: view_all → Returns a list of all active contracts and their base pricing
    • action: view
      • id:CONTRACTID → Returns details about an existing contract
    • action: extend
      • id:CONTRACTID → Extend prepaid contract by 30 days
    • action: autoextend
      • id:CONTRACTID
        • switch:enable/disable → Turn on/off automated extending by account credit (works only with sufficient credit)
    • action: order

For example, this call orders product 2050 – if your account credit is sufficient and the product is available, it will be provisioned directly:

curl -s --header "Content-Type: application/json" --request POST --data '{"email":"user@example.net",
"secret":"XXX", ",
"action":"order",
"id":"2050"}' https://api.combahton.net/v2


The API answers with: { „status“:„order_placed“, „id“:„CONTRACTID“ }

  • method: settings
    • action: sshkeys
      • ​​​​​​​​​​​​​​sshkeys:YOURKEYS → Update ssh keys by newly provided keys

Component: antiddos


The component antiddos provides you the ability to change the ddos-protection settings of your prefix. This requires a single call for each ip-address, prefixes are not allowed.

  • method: layer4
    • action: routing → ipaddr: SERVERIP
      • routing: dynamic → Disable layer4 ddos filters and change state to dynamic mode, filters will get activated in the event of an attack
      • routing: permanent → Enable layer4 ddos filters permanently, all traffic will be routed through the mitigation infrastructure
      • routing: dynamic_perm → Enable the layer4 ddos filters for 30 minutes, afterwards they will be switched back to dynamic automatically
  • method: layer7
    • action: routing → ipaddr: SERVERIP
      • routing: only_on → Enable layer7 ddos filters, all traffic on tcp port 80, 443 and 8443 will be verified, does not require to activate the layer4 filters and will be not active while the layer4 ddos filters are active
      • routing: only_off → Disable layer7 ddos filters and change state to direct routing, all tcp traffic on Port 80, 443, 8443 will be directly forwarded to your server - this does not affect the call routing: on
      • routing: on → This method works only in connection with active layer4 filters, it switches the layer7 filters on behind the layer4 filters - all traffic on tcp port 80, 443 and 8443 will be verified
      • routing: off → Disable the previously activated layer7 filters behind layer4 filters, all traffic after layer4 mitigation is directly forwarded to your server

Component: ipaddr

With the component ipaddr, you can view details of a ip-address or change the reverse-dns. The following methods are available:

  • method: view
    • action: ipv4
      • ipaddr: SERVERIP → View details of ipv4-address
    • action: ipv6
      • ipaddr: SERVERIP → View details of ipv6-address
  • method: rdns
    • action: ipv4
      • ipaddr: SERVERIP
        • ptr: NEWPTR → Set reverse-dns / ptr to NEWPTR
    • action: ipv6
      • ipaddr: SERVERIP
        • ptr: NEWPTR → Set reverse-dns / ptr to NEWPTR

The following example sets the ptr mail.example.net for 127.0.0.1:

{ "email":"user@example.net",
"secret":"XXX",
"component":"ipaddr",
"method":"rdns",
"action":"ipv4",
"ipaddr":"127.0.0.1",
"ptr":"mail.example.net" }

Component: ipsubnet

The component ipsubnet allows you to control the configuration of a subnet (e.g. nexthop).

The following methods are available:

  • method: nexthop →Change the routing / nexthop of a subnet - useful for automating common tasks and failover environments)
    • action: change
      • contract: CONTRACT
        • nexthop: XYZ.XYZ.XYZ.XYZ → IP-Address of the target server / nexthop on which you want to use the subnet)

Examples

{ "email":"user@example.net", "secret":"XXX",
"component":"ipsubnet",
"method":"nexthop",
"action":"change",
"contract":"XXX",
"nexthop":"XXX.XXX.XXX.XXX" }

Returns success or failed:

{ "status": "success" }
{ "status": "failed" }

Component: kvm

With the component kvm, you can control your kvm servers behaviour, the following methods are available:

  • method: server
    • action: view
      • id: CONTRACT → Display all information available for contract CONTRACT
    • action: control
      • id: CONTRACT
        • command: start
        • command: stop
        • command: reset
        • command: vnc
          • source: CLIENTIP → Enable VNC Access for client ipv4-address CLIENTIP and return the login password
    • action: reinstall_templates
      • id: CONTRACT → Return a list of available installation templates for CONTRACT
    • action: reinstall
      • id: CONTRACT
        • template: TEMPLATEID → Reinstall server with TEMPLATEID - a list of available templates can be returned with action: reinstall_templates

Examples

View server details

{ "email":"user@example.net",
"secret":"XXX",
"component":"kvm",
"method":"server",
"action":"view",
"id": "CONTRACTID" }

Returns:

{ "contract": "603XXX",
"product": "2037",
"node": "kvm2X",
"macaddr": "XX:XX:XX:XX:XX:XX",
"ostemplate": "none",
"status": "running",
"backup": "1" }

Open a vnc connection

{ "email":"user@example.net",
"secret":"XXX",
"component":"kvm",
"method":"server",
"action":"control",
"id": "603XX",
"command":"vnc",
"source":"89.33.XX.XX"}

Returns:

{
"status": "OK",
"source": "89.33.XX.XX",
"vnc_server": "ipmi-gw.combahton.net",
"vnc_port": "537XX",
"password": "XXXXXXXXXXXXXXX"
}