Using OSv REST API

Overview

Introduction

REST API allows to interact with a remote OSv instance in a secure, programmable way. Following REST conventions, request are sent with HTTP GET, POST, PUT and DELETE with path and query parameters and the results are returned in JSON format.

Using the API

You can use the API from an application, a browser or the curl command. For example to get the os version, after the host is up and the host ip address is 192.168.122.89 a call to curl http://192.168.122.89:8000/os/version will return the os version.

A call to curl -X POST http://192.168.122.89:8000/os/shutdown will shotdown the host

Swagger definition files

Swagger is a REST definition format in JSON. The latest definitions can be found on the git project at https://github.com/cloudius-systems/mgmt/ under httpserver/api-doc

When running OSv locally you can take advantage of ./scripts/run.py --api. This option will redirect local host port 8000 to the OSv HTTP server. This will allow you to use http://localhost:8000/ for the API UI and REST calls

The API is break into json files by their related content (os, java, files). Many languages support the Swagger definition format, and can use that definition to automatically create a client from it.

Using the Swagger-UI

The Swagger-UI is a part of the Swagger project and creates a web-based GUI from the swagger definition. An example of the latest API definition with the Swagger-UI can be found here: http://osv.io/api/swagger-ui/dist/index.html

Using the REST API over SSL

Configuring-SSL