API Specification - meridor/perspective-backend GitHub Wiki

Serialization format

We use JSON so you need to specify the following headers where needed:

Content-Type: application/json
Accept: application/json

Query API

This API is used to do SQL requests to storage.

POST /query

Processes SQL request(s) and returns results.

Input: SQL text and placeholder values:

$ cat request.json
[ {
  "sql" : "select id, name from projects name regexp :name: order by name asc",
  "parameters" : [ {
    "name" : "name",
    "value" : "selenium"
  } ]
} ]

Output: request status, number of rows, optional error message, column names and rows data:

$ curl -X POST -d @request.json -H Content-Type:application/json -H Accept:application/json http://example.com/query

[ {
  "status" : "success",
  "count" : 2,
  "data" : {
    "columnName" : [ "id", "name" ],
    "row" : [
        {"value" : [ "<uuid1>", "project-one" ]},
        {"value" : [ "<uuid2>", "project-two" ]}
    ]
  },
  "message" : ""
} ]

Instances API

Show instances

There's no separate url for listing instances. Use Query API to fetch respective columns.

POST /instances

Launches one more instances.

Input: a list of instances.

Output: 200 OK

TODO: add curl

POST /instances/delete

Deletes one or more instances. Input: a list of instance IDs

Output: 200 OK

$ curl -X POST --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/instances/delete

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

PUT /instances/reboot

Reboots one or more instances. Input: a list of instance IDs

Output: 200 OK

$ curl -X PUT --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/instances/reboot

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

PUT /instances/hard-reboot

Hard reboots (resets) one or more instances. Input: a list of instance IDs

Output: 200 OK

$ curl -X PUT --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/instances/hard-reboot

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

PUT /instances/start

Starts one or more instances. Input: a list of instance IDs

Output: 200 OK

$ curl -X PUT --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/instances/start

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

PUT /instances/shutdown

Shuts down one or more instances.

Input: a list of instance IDs

Output: 200 OK

$ curl -X PUT --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/instances/shutdown

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

PUT /instances/pause

Pauses one or more instances.

Input: a list of instance IDs

Output: 200 OK

$ curl -X PUT --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/instances/shutdown

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

PUT /instances/resume

Resumes one or more instances.

Input: a list of instance IDs

Output: 200 OK

$ curl -X PUT --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/instances/resume

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

PUT /instances/suspend

Suspends one or more instances.

Input: a list of instance IDs

Output: 200 OK

$ curl -X PUT --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/instances/suspend

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

PUT /instances/resize/{newFlavorID}

Resize one or more instances to new flavor.

Input: a list of instance IDs and flavor ID in url

Output: 200 OK

$ curl -X PUT --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/instances/resize/flavor-one

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

PUT /instances/rename

Renames one or more instances.

Input: a map of instance ID to new name pairs

Output: 200 OK

$ curl -X PUT --data '{ "id-one": "one-new-name", "id-two": "two-new-name" }' -H Accept:application/json http://example.com/instances/rename

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

PUT /instances/rebuild/{newImageID}

Rebuild one or more instances to new image.

Input: a list of instance IDs and image ID in url

Output: 200 OK

$ curl -X PUT --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/instances/rebuild/some-image

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

GET /instance/{ID}

Gets instance by ID.

Input: instance ID in url

Output: serialized instance

$ curl -H Accept:application/json http://example.com/instances/5653608a-117c-3ba8-80b0-36af42961fdb

{
  "id" : "5653608a-117c-3ba8-80b0-36af42961fdb",
  "realId" : "dec960ca-7507-445b-b993-e194f5eeec22",
  "timestamp" : "2016-12-20T16:58:56+03:00[Europe/Moscow]",
  "created" : "2016-09-16T15:37:33+03:00[Europe/Moscow]",
  "cloudId" : "test-cloud",
  "cloudType" : "openstack",
  "projectId" : "71609a7f-0641-36cc-b704-db3b5b76c78e",
  "name" : "test-instance",
  "flavor" : {
    "id" : "c0a70fa5-8c4c-4274-bbb0-b7590ad9e9a3",
    "name" : "test-flavor",
    "ram" : 4092,
    "vcpus" : 2,
    "rootDisk" : 100,
    "ephemeralDisk" : 0,
    "hasSwap" : false,
    "isPublic" : true
  },
  "image" : {
    "id" : "3efc2dc8-4c35-3c11-862a-c08b58d6f9d9",
    "realId" : "28dc791c-9aa5-461f-a347-5a2107736229",
    "timestamp" : "2016-11-24T14:59:42+03:00[Europe/Moscow]",
    "created" : "2016-09-15T18:16:09+03:00[Europe/Moscow]",
    "cloudId" : "test-cloud",
    "cloudType" : "openstack",
    "name" : "test-image",
    "state" : "saved",
    "metadata" : {
      "entry" : [ {
        "key" : "region",
        "value" : "test-region"
      } ]
    },
    "projectId" : [ "3d6f17b9-584b-3169-819b-9241526a4b89" ]
  },
  "keypair" : { },
  "state" : "launched",
  "isLocked" : false,
  "metadata" : {
    "entry" : [ {
      "key" : "region",
      "value" : "test-region"
    } ]
  },
  "address" : [ "192.168.1.1" ],
  "networks" : [ {
    "id" : "3bc8e8b7-eabc-4e4b-a678-dac251be4625",
    "name" : "TESTNETS",
    "state" : "ACTIVE",
    "isShared" : false,
    "subnets" : [ ]
  } ]
}

Images API

Show images

There's no separate url for listing images. Use Query API to fetch respective columns.

POST /images

Adds one more images.

Input: a list of images

TODO: add curl

POST /images/delete

Deletes one or more images. Input: a list of image IDs

Output: 200 OK

$ curl -X POST --data '[ "id-one", "id-two" ]' -H Accept:application/json http://example.com/images/delete

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

Service API

GET /ping

Returns whether API is operating normally. To be used in SLB checking logic.

Input: nothing

Output: 200 OK or 503 Service Unavailable

$ curl -H Accept:application/json http://example.com/ping

HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: application/json
Content-Length: 0

GET /version

Returns API version as plain text.

Input: nothing

Output: API version or unknown

$ curl -H Accept: text/plain http://example.com/version

1.3.4

GET /operations

Returns a list of supported operations for each cloud.

Input: nothing

Output: a map cloud type -> list of supported operations

$ curl -H Accept:application/json http://example.com/operations

{
  "OPENSTACK" : ["REBOOT", "RESIZE"]
}

More projects:

  • Stecker - a lightweight plugin framework for Java 8+
  • Ggr - a lightweight route and proxy to build Selenium clusters
  • Selenoid - lightweight Selenium hub implementation working with Docker containers
⚠️ **GitHub.com Fallback** ⚠️