API

DocumentsAPIArukas API Reference

Arukas API Reference


Overview

The Arukas API provides programmable access interface for resources, which extends and integrates Arukas application with other services.
Creating apps, provisioning, and performing other tasks through Arukas API empowers to automate your daily workflow.

Authentication

The API keys consist of API token and secret token. You can generate them in Arukas user control panel.
To follow along with this document smoothly, it would be nice to create including a ~/.netrc line of code below.
machine app.arukas.io login #{ARUKAS_JSON_API_TOKEN} password #{ARUKAS_JSON_API_SECRET}

Clients

All Clients are required to request HTTPS connection to https://app.arukas.io/api specifying the inAccept: application/vnd.api+json Accept header.

Apps

Resource Description
POST /api/apps Create an application
GET /api/apps List all applications
GET /api/apps/{APP_ID} Show an application
DELETE /api/apps/{APP_ID} Delete an application

Services

Resource Description
GET /api/services List all Services
GET /api/services/{SERVICE_ID} Show a Service
PATCH /api/services/{SERVICE_ID} Update a Service
POST /api/services/{SERVICE_ID}/power Power on a Service
DELETE /api/services/{SERVICE_ID}/power Power off a Service

API REFERENCE

POST /api/apps
Create an application

Errors

Code Description
409 Cannot create application.
422 Required Paramters Missing.

Examples

# Example Request
$ curl -n -X POST -H "Content-Type: application/json" https://app.arukas.io/api/apps -d \
'{
  "data":{
    "type": "apps",
    "attributes": {
      "name": "myapp"
    },
    "relationships": {
      "service": {
        "data": {
          "temp-id": "1",
          "type": "services"
        }
      }
    }
  },
  "included": [
    {
      "temp-id": "1",
      "type": "services",
      "attributes": {
        "command": "",
        "custom-domain": "",
        "image": "nginx",
        "instances": 1,
        "ports": [
          {
            "number": "80",
            "protocol": "tcp"
          },
          {
            "number": "443",
            "protocol": "tcp"
          }
        ],
        "environment": [
          {
            "key": "key1",
            "value": "value2"
          },
          {
            "key": "key2",
            "value": "value2"
          }
        ],
        "subdomain": "example"
      },
      "relationships": {
        "service-plan": {
          "data": {
            "type": "service-plans",
            "id": "jp-tokyo/hobby"
          }
        }
      }
    }
  ]
}'
# Example Response
{
  "data": {
    "id": "837ff771-8db5-48cf-a40c-dae9fc37e59d",
    "type": "apps",
    "attributes": {
      "name": "myapp",
      "created-at": "2018-02-12T18:28:33.721Z",
      "updated-at": "2018-02-12T18:28:33.721Z"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "72e00ac7-19a8-42da-b35a-43bdf812b461",
          "type": "users"
        }
      },
      "service": {
        "data": {
          "id": "7022a19e-ba83-42eb-a608-ff5ae272a12a",
          "type": "services"
        }
      }
    }
  },
  "included": [
    {
      "id": "7022a19e-ba83-42eb-a608-ff5ae272a12a",
      "type": "services",
      "attributes": {
        "app-id": "837ff771-8db5-48cf-a40c-dae9fc37e59d",
        "image": "nginx",
        "command": "",
        "instances": 1,
        "cpus": 0.1,
        "memory": null,
        "environment": [
          {
            "key": "key1",
            "value": "value2"
          },
          {
            "key": "key2",
            "value": "value2"
          }
        ],
        "ports": [
          {
            "number": 80,
            "protocol": "tcp"
          },
          {
            "number": 443,
            "protocol": "tcp"
          }
        ],
        "port-mappings": null,
        "created-at": "2018-02-12T18:28:33.751Z",
        "updated-at": "2018-02-12T18:28:33.751Z",
        "status": "stopped",
        "subdomain": "example",
        "endpoint": "example.arukascloud.io",
        "custom-domain": null,
        "last-instance-failed-at": null,
        "last-instance-failed-status": null
      },
      "relationships": {
        "app": {
          "data": {
            "id": "837ff771-8db5-48cf-a40c-dae9fc37e59d",
            "type": "apps"
          }
        },
        "service-plan": {
          "data": {
            "id": "jp-tokyo/hobby",
            "type": "service-plans"
          }
        }
      }
    },
    {
      "id": "jp-tokyo/hobby",
      "type": "service-plans",
      "attributes": {
        "code": "jp-tokyo_hobby_v1",
        "name": "Hobby",
        "region-id": 1,
        "version": 1,
        "cpus": "0.1",
        "memory": 512,
        "price": 450,
        "created-at": "2018-02-12T16:45:24.205Z",
        "updated-at": "2018-02-12T16:45:24.205Z"
      },
      "relationships": {
        "region": {
          "data": {
            "id": "1",
            "type": "regions"
          }
        }
      }
    }
  ]
}

Params

Param name Description
:data 
required
Validations:

  • Must be a Hash
:data[:id] 
required
Application UUID. Total of 36 characters (32 alphanumeric characters and four hyphens). For example: 123e4567-e89b-12d3-a456-426655440000

Validations:

  • Must be a String
:data[:type] 
required
Application type: apps

Validations:

  • Must be a String
:data[:attributes] 
optional , nil allowed
Validations:

  • Must be a Hash
:data[:attributes][:name] 
optional , nil allowed
Application name

Validations:

  • Must be a String
:data[:attributes][:created-at] 
optional , nil allowed
Creation timestamp

Validations:

  • Must be a Time
:data[:attributes][:updated-at] 
optional , nil allowed
Updated timestamp

Validations:

  • Must be a Time
:data[:relationships] 
optional , nil allowed
Validations:

  • Must be a Hash
:data[:relationships][:user] 
optional , nil allowed
Validations:

  • Must be a Hash
:data[:relationships][:user][:data] 
optional , nil allowed
Validations:

  • Must be a Hash
:data[:relationships][:user][:data][:id] 
optional , nil allowed
User UUID.

Validations:

  • Must be a String
:data[:relationships][:user][:data][:type] 
optional , nil allowed
User type: users

Validations:

  • Must be a String
:data[:relationships][:service] 
optional , nil allowed
Validations:

  • Must be a Hash
:data[:relationships][:service][:data] 
required
Validations:

  • Must be a Hash
:data[:relationships][:service][:data][:id] 
optional , nil allowed
Service UUID. Total of 36 characters (32 alphanumeric characters and four hyphens). For example: 123e4567-e89b-12d3-a456-426655440000

Validations:

  • Must be a String
:data[:relationships][:service][:data][:temp_id] 
required
Service temp ID

Validations:

  • Must be a Integer
:data[:relationships][:service][:data][:type] 
required
Service type: services

Validations:

  • Must be a String
:included 
required
Validations:

  • Must be an Array of nested elements
:included[:id] 
optional , nil allowed
Service UUID

Validations:

  • Must be a String
:included[:temp_id] 
required
Service temp ID

Validations:

  • Must be a Integer
:included[:type] 
required
Service type: services

Validations:

  • Must be a String
:included[:attributes] 
required
Validations:

  • Must be a Hash
:included[:attributes][:app-id] 
optional , nil allowed
Application UUID

Validations:

  • Must be a String
:included[:attributes][:image] 
required
Docker image name to use for the Application.

Validations:

  • Must be a String
:included[:attributes][:command] 
optional , nil allowed
Application to run specified. (maximum is 4096 characters)

Validations:

  • Must be a String
:included[:attributes][:instances] 
required
Number (quantity) of Application instances. (Range: 1 <= value <= 10)

Validations:

  • Must be a Integer
:included[:attributes][:cpus] 
optional , nil allowed
virtual CPU(vCPU) of Applications. (This value is inherited from Service Plan.)

Validations:

  • Must be a Float
:included[:attributes][:memory] 
optional , nil allowed
Memory size of Application instances. (This value is inherited from Service Plan.)

Validations:

  • Must be a Integer
:included[:attributes][:environment] 
optional , nil allowed
Application environment variables.

Validations:

  • Must be an array of any type
:included[:attributes][:key] 
optional , nil allowed
Environment variable key

Validations:

  • Must be a String
:included[:attributes][:value] 
optional , nil allowed
Environment variable value

Validations:

  • Must be a String
:included[:attributes][:ports] 
optional , nil allowed
Application ports.

Validations:

  • Must be an array of any type
:included[:attributes][:number] 
optional , nil allowed
Port Number. (Port Range: 0 <= value <= 65535)

Validations:

  • Must be a Integer
:included[:attributes][:protocol] 
optional , nil allowed
Port protocol. (Protocol: tcp or udp)

Validations:

  • Must be a String
:included[:attributes][:port-mappings] 
optional , nil allowed
Application port mappings.

Validations:

  • Must be an array of any type
:included[:attributes][:container-port] 
optional , nil allowed
Port number. (Port Range: 0 <= value <= 65535)

Validations:

  • Must be a Integer
:included[:attributes][:host] 
optional , nil allowed
Hostname.

Validations:

  • Must be a String
:included[:attributes][:protocol] 
optional , nil allowed
Port protocol. (Protocol: tcp or udp)

Validations:

  • Must be a String
:included[:attributes][:service-port] 
optional , nil allowed
Port number. (Port Range: 0 <= value <= 65535)

Validations:

  • Must be a Integer
:included[:attributes][:created-at] 
optional , nil allowed
Created timestamp.

Validations:

  • Must be a Time
:included[:attributes][:updated-at] 
optional , nil allowed
Updated timestamp.

Validations:

  • Must be a Time
:included[:attributes][:status] 
optional , nil allowed
Status of Application. Either booting or terminated or running or stopping or stopped or rebooting.

Validations:

  • Must be a String
:included[:attributes][:subdomain] 
optional , nil allowed
Subdomain name of Application. subdomain value with a maximum length of 63 characters.

Validations:

  • Must be a String
:included[:attributes][:endpoint] 
optional , nil allowed
HTTP/HTTPS Endpoint URL of Application.

Validations:

  • Must be a String
:included[:attributes][:custom-domain] 
optional , nil allowed
Custom domain name of Application.

Validations:

  • Must be a String
:included[:attributes][:last-instance-failed-at] 
optional , nil allowed
Last instance failed at.

Validations:

  • Must be a Time
:included[:attributes][:last-instance-failed-status] 
optional , nil allowed
Last instance failed status message.

Validations:

  • Must be a String
:included[:relationships] 
optional , nil allowed
Validations:

  • Must be a Hash
:included[:relationships][:app] 
optional , nil allowed
Validations:

  • Must be a Hash
:included[:relationships][:app][:data] 
optional , nil allowed
Validations:

  • Must be a Hash
:included[:relationships][:app][:data][:id] 
optional , nil allowed
Application UUID. Total of 36 characters (32 alphanumeric characters and four hyphens). For example: 123e4567-e89b-12d3-a456-426655440000

Validations:

  • Must be a String
:included[:relationships][:app][:data][:type] 
optional , nil allowed
Application type: apps

Validations:

  • Must be a String
:included[:relationships][:service-plan] 
required
Validations:

  • Must be a Hash
:included[:relationships][:service-plan][:data] 
required
Validations:

  • Must be a Hash
:included[:relationships][:service-plan][:data][:id] 
required
Service plan ID. Either jp-tokyo/free or jp-tokyo/hobby or jp-tokyo/standard-1 or jp-tokyo/standard-2

Validations:

  • Must be a String
:included[:relationships][:service-plan][:data][:type] 
required
Service plan type: service-plans

Validations:

  • Must be a String

 

GET /api/apps
List all applications

GET /api/apps/{APP_ID}
Show an application

Errors

Code Description
404 No such app

Examples

# Example Request
$ curl -n -X GET https://app.arukas.io/api/apps/e074f90a-764a-4350-87bf-46857e25da4a
# Example Response
{
  "data": {
    "id": "e074f90a-764a-4350-87bf-46857e25da4a",
    "type": "apps",
    "attributes": {
      "name": "myapp",
      "created-at": "2018-02-12T16:45:24.280Z",
      "updated-at": "2018-02-12T16:45:24.280Z"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "72e00ac7-19a8-42da-b35a-43bdf812b461",
          "type": "users"
        }
      },
      "service": {
        "data": {
          "id": "950f24ba-cc0b-495d-9ed7-16e332649637",
          "type": "services"
        }
      }
    }
  }
}

Params

Param name Description
id 
required
UUID of Application. Total of 36 characters (32 alphanumeric characters and four hyphens). For example: 123e4567-e89b-12d3-a456-426655440000

Validations:

  • Must be a String

 


 

DELETE /api/apps/{APP_ID}
Delete an application

Errors

Code Description
404 No such application
422 Unprocessable Entity

Examples

# Example Request
$ curl -n -X DELETE https://app.arukas.io/api/apps/270f48f7-e4f9-4cf7-81b6-7b982eb0491a
# Example Response
null

Params

Param name Description
id 
required
Application UUID. Total of 36 characters (32 alphanumeric characters and four hyphens). For example: 123e4567-e89b-12d3-a456-426655440000

Validations:

  • Must be a String

 


 

GET /api/services
List all Services

GET /api/services/{SERVICE_ID}
Show a Service

Errors

Code Description
404 No such service

Examples

# Example Request
$ curl -n -X GET https://app.arukas.io/api/services/950f24ba-cc0b-495d-9ed7-16e332649637
# Example Response
{
  "data": {
    "id": "950f24ba-cc0b-495d-9ed7-16e332649637",
    "type": "services",
    "attributes": {
      "app-id": "e074f90a-764a-4350-87bf-46857e25da4a",
      "image": "nginx",
      "command": null,
      "instances": 1,
      "cpus": 0.1,
      "memory": null,
      "environment": null,
      "ports": [
        {
          "protocol": "tcp",
          "number": 80
        }
      ],
      "port-mappings": null,
      "created-at": "2018-02-12T16:45:24.389Z",
      "updated-at": "2018-02-12T16:47:48.091Z",
      "status": "stopped",
      "subdomain": "example",
      "endpoint": "example.arukascloud.io",
      "custom-domain": null,
      "last-instance-failed-at": null,
      "last-instance-failed-status": null
    },
    "relationships": {
      "app": {
        "data": {
          "id": "e074f90a-764a-4350-87bf-46857e25da4a",
          "type": "apps"
        }
      },
      "service-plan": {
        "data": {
          "id": "jp-tokyo/hobby",
          "type": "service-plans"
        }
      }
    }
  }
}

Params

Param name Description
id 
required
UUID of Services. Total of 36 characters (32 alphanumeric characters and four hyphens). For example: 123e4567-e89b-12d3-a456-426655440000

Validations:

  • Must be a String

 


 

PATCH /api/services/{SERVICE_ID}
Update a Service

Errors

Code Description
404 No such service
422 Unprocessable Entity

Examples

# Example Request
$ curl -n -X PATCH -H "Content-Type: application/json" https://app.arukas.io/api/services/950f24ba-cc0b-495d-9ed7-16e332649637 -d \
'{
  "data": {
    "id": "950f24ba-cc0b-495d-9ed7-16e332649637",
    "type": "services",
    "attributes": {
      "app-id": "e074f90a-764a-4350-87bf-46857e25da4a",
      "image": "nginx",
      "command": null,
      "instances": 3,
      "environment": null,
      "ports": [
        {
          "protocol": "tcp",
          "number": 80
        }
      ]
    },
    "relationships": {
      "app": {
        "data": {
          "id": "e074f90a-764a-4350-87bf-46857e25da4a",
          "type": "apps"
        }
      },
      "service-plan": {
        "data": {
          "id": "jp-develop/hobby",
          "type": "service-plans"
        }
      }
    }
  }
}'
# Example Response
{
  "data": {
    "id": "950f24ba-cc0b-495d-9ed7-16e332649637",
    "type": "services",
    "attributes": {
      "app-id": "e074f90a-764a-4350-87bf-46857e25da4a",
      "image": "nginx",
      "command": null,
      "instances": 3,
      "cpus": 0.1,
      "memory": null,
      "environment": null,
      "ports": [
        {
          "protocol": "tcp",
          "number": 80
        }
      ],
      "port-mappings": [
        [
          {
            "container-port": 80,
            "host": "seaof-172-17-0-1.arukascloud.io",
            "protocol": "tcp",
            "service-port": 12464
          }
        ]
      ],
      "created-at": "2018-02-12T16:45:24.389Z",
      "updated-at": "2018-02-12T17:53:29.742Z",
      "status": "running",
      "subdomain": "example",
      "endpoint": "example.arukascloud.io",
      "custom-domain": null,
      "last-instance-failed-at": null,
      "last-instance-failed-status": null
    },
    "relationships": {
      "app": {
        "data": {
          "id": "e074f90a-764a-4350-87bf-46857e25da4a",
          "type": "apps"
        }
      },
      "service-plan": {
        "data": {
          "id": "jp-tokyo/hobby",
          "type": "service-plans"
        }
      }
    }
  }
}

Params

Param name Description
:data 
required
Validations:

  • Must be a Hash
:data[:id] 
optional , nil allowed
Service ID. Total of 36 characters (32 alphanumeric characters and four hyphens). For example: 123e4567-e89b-12d3-a456-426655440000

Validations:

  • Must be a String
:data[:type] 
optional , nil allowed
Service type: services

Validations:

  • Must be a String
:data[:attributes] 
required
Validations:

  • Must be a Hash
:data[:attributes][:app-id] 
optional , nil allowed
Application ID. Total of 36 characters (32 alphanumeric characters and four hyphens). For example: 123e4567-e89b-12d3-a456-426655440000

Validations:

  • Must be a String
:data[:attributes][:image] 
required
Docker image name to use for the Application.

Validations:

  • Must be a String
:data[:attributes][:command] 
optional , nil allowed
Application to run specified. (maximum is 4096 characters)

Validations:

  • Must be a String
:data[:attributes][:instances] 
required
Number of Application instances. (Range: 1 <= value <= 10)

Validations:

  • Must be a Integer
:data[:attributes][:cpus] 
optional , nil allowed
Virtual CPU(vCPU) of Applications. (This value is inherited from Service Plan.)

Validations:

  • Must be a Float
:data[:attributes][:memory] 
optional , nil allowed
Memory size of Application instances. (This value is inherited from Service Plan.)

Validations:

  • Must be a Integer
:data[:attributes][:environment] 
optional , nil allowed
Application environment variables.

Validations:

  • Must be an array of any type
:data[:attributes][:key] 
optional
Environment variable key

Validations:

  • Must be a String
:data[:attributes][:value] 
optional
Environment variable value

Validations:

  • Must be a String
:data[:attributes][:ports] 
optional , nil allowed
Application ports.

Validations:

  • Must be an array of any type
:data[:attributes][:number] 
optional
Port Number. (Port Range: 0 <= value <= 65535)

Validations:

  • Must be a Integer
:data[:attributes][:protocol] 
optional
Port protocol. (Protocol: tcp or udp)

Validations:

  • Must be a String
:data[:attributes][:port-mappings] 
optional , nil allowed
Application port mappings.

Validations:

  • Must be an array of any type
:data[:attributes][:container-port] 
optional
Port number. (Port Range: 0 <= value <= 65535)

Validations:

  • Must be a Integer
:data[:attributes][:host] 
optional
Hostname.

Validations:

  • Must be a String
:data[:attributes][:protocol] 
optional
Port protocol. (Protocol: tcp or udp)

Validations:

  • Must be a String
:data[:attributes][:service-port] 
optional
Port number. (Port Range: 0 <= value <= 65535)

Validations:

  • Must be a Integer
:data[:attributes][:created-at] 
optional , nil allowed
Created timestamp.

Validations:

  • Must be a Time
:data[:attributes][:updated-at] 
optional , nil allowed
Updated timestamp.

Validations:

  • Must be a Time
:data[:attributes][:status] 
optional , nil allowed
Status of Application. Either booting or terminated or running or stopping or stopped or rebooting.

Validations:

  • Must be a String
:data[:attributes][:subdomain] 
optional , nil allowed
Subdomain name of Application. subdomain value with a maximum length of 63 characters.

Validations:

  • Must be a String
:data[:attributes][:endpoint] 
optional , nil allowed
HTTP/HTTPS Endpoint URL of Application.

Validations:

  • Must be a String
:data[:attributes][:custom-domain] 
optional , nil allowed
Custom domain name of Application.

Validations:

  • Must be a String
:data[:attributes][:last-instance-failed-at] 
optional , nil allowed
Last instance failed at.

Validations:

  • Must be a Time
:data[:attributes][:last-instance-failed-status] 
optional , nil allowed
Last instance failed status message.

Validations:

  • Must be a String
:data[:relationships] 
optional
Validations:

  • Must be a Hash
:data[:relationships][:app] 
optional
Validations:

  • Must be a Hash
:data[:relationships][:app][:data] 
optional
Validations:

  • Must be a Hash
:data[:relationships][:app][:data][:id] 
optional , nil allowed
Application ID

Validations:

  • Must be a String
:data[:relationships][:app][:data][:type] 
optional , nil allowed
Application type: apps

Validations:

  • Must be a String
:data[:relationships][:service-plan] 
optional
Validations:

  • Must be a Hash
:data[:relationships][:service-plan][:data] 
optional
Validations:

  • Must be a Hash
:data[:relationships][:service-plan][:data][:id] 
optional , nil allowed
ServicePlan ID

Validations:

  • Must be a String
:data[:relationships][:service-plan][:data][:type] 
optional , nil allowed
ServicePlan type: service-plans

Validations:

  • Must be a String

 

POST /api/services/{SERVICE_ID}/power
Power on a Service

Errors

Code Description
403 You have been not allowed to boot app due to penalty.
404 No such service
409 The app is not bootable.

Examples

# Example Request
$ curl -n -X POST https://app.arukas.io/api/services/950f24ba-cc0b-495d-9ed7-16e332649637/power
# Example Response
{
  "data": {
    "id": "950f24ba-cc0b-495d-9ed7-16e332649637",
    "type": "marathon-apps",
    "attributes": {
      "uuid": "950f24ba-cc0b-495d-9ed7-16e332649637",
      "image": "nginx",
      "cpus": 0.1,
      "memory": null,
      "instances": 1,
      "ports": [
        {
          "protocol": "tcp",
          "number": 80
        }
      ],
      "environment": null,
      "created-at": "2018-02-12T16:45:24.389Z",
      "updated-at": "2018-02-12T17:50:08.969Z",
      "zone-id": null,
      "command": null,
      "port-mappings": null,
      "status": "stopped",
      "subdomain": "dev-0242ac120006-sub-1",
      "custom-domain": null
    },
    "relationships": {
      "app": {
        "data": {
          "id": "e074f90a-764a-4350-87bf-46857e25da4a",
          "type": "apps"
        }
      },
      "running-zone": {
        "data": null
      }
    }
  }
}

Params

Param name Description
id 
required
UUID of Services. Total of 36 characters (32 alphanumeric characters and four hyphens). For example: 123e4567-e89b-12d3-a456-426655440000

Validations:

  • Must be a String

 


 

DELETE /api/services/{SERVICE_ID}/power
Power off a Service

Errors

Code Description
404 No such service

Examples

# Example Request
$ curl -n -X DELETE https://app.arukas.io/api/services/950f24ba-cc0b-495d-9ed7-16e332649637/power
# Example Response
null

Params

Param name Description
id 
required
UUID of Services. Total of 36 characters (32 alphanumeric characters and four hyphens). For example: 123e4567-e89b-12d3-a456-426655440000

Validations:

  • Must be a String