REST API for Developers

SAYMON API belongs to the REpresentational State Transfer (REST) category. It allows to perform "RESTful" operations such as reading, modifying, adding or deletion data from a cloud account or on-site installation.

New methods and their description are constantly added here: https://api.saymon.tech/

What can be done using the SAYMON API?

Every operation available in SAYMON web interface can be implemented with API, for example:

and many more.

What API commands are allowed?

SAYMON API has been implemented as JSON over HTTP and allows the following REST Commands:

Command Purpose

GET

Fetch information about existing items

POST

Create new items

PUT

Update and modify existing items

PATCH

Update and modify existing items

DELETE

Remove existing items

Access rights

Abilities to access to data or perform actions depends on the permissions available for the SAYMON user account.

Authentication

There are several options which can be used for authentication.

Basic Access Authorization

Basic authentication can be used in order to get info about the account as follows:

$curl -v -u login:password -H "Content-Type: application/json" -X GET https://your.server.name/node/api/users/current

where:

  • login is account’s username,

  • password account’s password,

  • your.server.name is the server’s hostname.

Session ID (Cookie)

The system allows to store session ID in Cookies and use the ID in next requests:

curl
$curl -v --cookie-jar cookies.txt -H "Content-Type: application/json" -X POST --data '{"login": "login", "password": "password"}' https://your.server.name/node/api/users/session
$curl -v --cookie cookies.txt -H "Content-Type: application/json" -X GET https://your.server.name/node/api/users/current
ajax
$.ajax
({
  type: "POST",
  url: "https://your.server.name/node/api/users/session",
  dataType: 'json',
  async: true,
  data:
  {
    "login": "login",
    "password": "password"
  },
  success: function (res){
    console.log('Thanks for your login!');
    console.log('Session ID:'+res);
  },
  error: function () {
    console.log('Login failed!');
  }
});

where:

  • login is account’s username,

  • password account’s password,

  • your.server.name is the server’s hostname.

API Key (API Token)

In order to obtain an API Token it is necessary to:

  1. Login with these credentials to the system web interface.

  2. Click on the login at the top right corner.

  3. Open the System configuration window.

The API token will be available in the field Authorization link:https://your.server.name/?auth-token=52cc80e1-e2d8-4cff-a242-dfcfb538b585.

It can be used in each request as follows:

$curl -v -H "Content-Type: application/json" -X GET https://your.server.name/node/api/users/current?api-token=52cc80e1-e2d8-4cff-a242-dfcfb538b585

where:

  • your.server.name is the server’s hostname.