Chapter 1: Introduction

	cOS Core 15.00.01 REST API Guide	Next

	Note: This document is also available in other formats
A PDF version of this document along with all current and older documentation in PDF format can be found at https://my.clavister.com. It is also available as a single HTML page.

Note: This document is also available in other formats

A PDF version of this document along with all current and older documentation in PDF format can be found at https://my.clavister.com.

It is also available as a single HTML page.

The cOS Core software provides a REST API which allows certain aspects of its operation to be controlled by software running on an external computer.

The REST API functions by an external computer sending HTTP or HTTPS messages to the IP address of a cOS Core Ethernet interface over an IP network. cOS Core then processes the message and returns any reply in an HTTP/HTTPS message. Any data sent in messages uses the JSON format.

	Note: JSON data is shown reformatted for readability
	The JSON data sent back by cOS Core will be one continuous stream of characters without white space. The JSON output shown in this publication has been reformatted to make it more readable.

Using HTTP POST

In some cases, cOS Core must receive an HTTP POST from the external system using the REST API. For example, when sending server loading data for server load balancing. It should be noted that when using POST, the content-type header must be set to:

		application/x-www-form-urlencoded

Enabling REST API Access in cOS Core

Allowing access by the REST API must be explicitly configured in cOS Core by creating a RemoteManagementREST object. The properties of this object determine what restrictions are placed on REST API access. These properties include the following:

Protocol used (HTTP or HTTPS). Encrypting messages with HTTPS is recommended.
The interface to accept connections from external clients on. The external computer will send REST API messages to the IP address of this interface.
The source IP(s) to accept connections from external clients on.
The access level permitted to clients (read only or read/write).
The option to require REST API authentication using a basic access authentication schema with username/password credentials.

An Example of Enabling the REST API

Before the REST API can be used, it must be enabled by creating a REST API Management object in the cOS Core configuration and setting the properties of this object to the appropriate values. The example below shows how this is done.

Example 1.1. Enabling the REST API

This example will create a new REST_managment object called my-rest-api. This will allow read/write HTTPS communication only on the if3 interface and only from the network mgmt-net. Credentials will be required for access with a username of my-admin-name and password of my-admin-pass.

Command-Line Interface

Device:/> add RemoteManagement RemoteMgmtREST
			Name=my-rest-api
			Interface=if3
			Network=mgmt-net
			HTTPS=Yes
			AccessLevel=ReadWrite
			BasicAUTH=Yes
			Username=my-admin-name
			Password=my-admin-pass

Web Interface

Go to: System > Device > Remote Management
Select Add > REST API Management
Enter Name: my-rest-api
Enable HTTPS
Enter Interface: if3
Enter Network: mgmt-net
Select Access Level to be Read/Write
Enable Basic Auth
Enter Username: my-admin-name
Enter Password: my-admin-pass
Click OK