You are here: Welcome to BlueOnyx» Features» API (v2) Documentation» Object management

API (v2) Object management

Command Supported Notes
GET ✅ Supports optional namespace
SET ✅ Supports optional namespace
CREATE ✅ Supports key/value args
DESTROY ✅ Basic object destruction
GETOBJECT ✅ Find + GET in one
GETALL ✅ Bulk fetch of objects

GET:

A GET request is used to fetch data from CODB. The desired numerical Object ID (OID) must be given. If a GET request only gives the Object ID, then the data of said object (if present) is returned. If Object ID and a desired NameSpace are given, then the data of the NameSpace of that Object will be returned.

Object IDs can be determined with the FIND or FINDX command. Names of NameSpaces can be determined with the NAMES command.

Local request (without NameSpace):

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -d '{
  "cmd": "GET 6",
  "user": "admin",
  "sessionid": "SESSION-ID"
}' | jq

Local request (with NameSpace):

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -d '{
  "cmd": "GET 6 . Email",                 
  "user": "admin",
  "sessionid": "SESSION-ID"
}' | jq

Remote request (without NameSpace):

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -H "Content-Type: application/json" 
  -H "X-Client-Secret: CLIENT-SECRET" 
  -d '{
  "cmd": "GET 6",
  "token": "TOKEN"
}' | jq

Remote request (with NameSpace):

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -H "Content-Type: application/json" 
  -H "X-Client-Secret: CLIENT-SECRET" 
  -d '{
  "cmd": "GET 6 . Email",                 
  "token": "TOKEN"
}' | jq

Response (success):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "DATA": {
      "CLASS": "User",
      "CLASSVER": "1.0",
      "NAMESPACE": "",
      "OID": "6",
      "capLevels": "",
      "capabilities": "",
      "crypt_password": "XXXX",
      "desc_readonly": "0",
      "description": "",
      "emailDisabled": "0",
      "enabled": "1",
      "ftpDisabled": "0",
      "fullName": "Administrator",
      "gui_theme": "elmer",
      "gui_theme_timer": "0",
      "localePreference": "en_US",
      "md5_password": "XXXX",
      "name": "admin",
      "noFileCheck": "0",
      "password": "",
      "shell": "",
      "site": "",
      "sortName": "",
      "stylePreference": "BlueOnyx",
      "systemAdministrator": "1",
      "uiRights": "",
      "ui_enabled": "1",
      "volume": "/home"
    }
  }
}

Response (fail):

{
  "status": 401,
  "message": "GOODBYE",
  "data": {
    "errors": [
      {
        "code": 300,
        "message": "UNKNOWN OBJECT 6"
      },
      {
        "code": 401,
        "message": "FAIL"
      }
    ]
  }
}

SET:

SET requests are used to update the values (or data) of existing CODB Objects or NameSpaces. In order to write to an Object the Object ID must be known. If no NameSpace is given, then the Object itself is written to. If a NameSpace is given, then the specified NameSpace will be updated with the SET request data.

Local request (without NameSpace):

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -d '{
  "cmd": "SET 6 localePreference = \"en_US\"",
  "user": "admin",
  "sessionid": "SESSION-ID"
}' | jq

Remote request (with NameSpace):

curl -k -s -X POST https://API-IP:9092/v2/cce -H "Content-Type: application/json" 
  -H "X-Client-Secret: CLIENT-SECRET" 
  -d '{ "cmd": "SET 6 . Email \"forwardEmail\" = \"0\"", "token": "TOKEN" }' | jq

Response (success):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "DATA": {}
  }
}

Response (fail):

{
  "status": 401,
  "message": "GOODBYE",
  "data": {
    "DATA": {},
    "errors": [
      {
        "code": 302,
        "message": "BAD DATA 6 forwardXmail \"[[base-cce.unknownAttr]]\""
      },
      {
        "code": 401,
        "message": "FAIL"
      }
    ]
  }
}

CREATE:

The function CREATE is used to create CODB Objects. You must specify which Class of Object to create. If that Class has NameSpaces, these will be automatically added as well with the default values. During CREATE you can (and in many cases must!) pass key/value pairs to be set in the newly created Object. You don't have to set all of them (in which case defaults will be set). But certain Objects have values that must be set, must be unique or conform to certain rules. Otherwise the CREATE transaction will fail.

Below are examples on how to create a Vsite from a localhost API call and a remote API call.

Upon successful execution the CREATE command will return the Object ID (OID) of the newly created Object. On failure it will return errors and warnings that may help to troubleshoot the issue. Typical failures during CREATE are missing required values or certain handlers failing the transaction because on or the other condition or requirement wasn't met. In our remote usage example the failure was that the IP address 192.168.151.218 isn't allowed to be used on the BlueOnyx in question.

Local request:

curl -k -s -X POST https://127.0.0.1:9092/v2/cce   -H "Content-Type: application/json"   -d '{
    "cmd": "CREATE",
    "class": "Vsite",
    "user": "admin",
    "sessionid": "REPLACE_WITH_SESSION_ID",
    "data": {
      "mailAliases": "",
      "fqdn": "t2.smd.net",
      "mailCatchAll": "",
      "hostname": "t2",
      "ipaddr": "192.168.151.218",
      "ipaddrIPv6": "",
      "userPrefixEnabled": "0",
      "maxusers": "25",
      "volume": "/home",
      "dns_auto": "0",
      "userPrefixField": "",
      "site_preview": "0",
      "createdUser": "admin",
      "emailDisabled": "0",
      "domain": "smd.net",
      "prefix": "",
      "webAliases": "",
      "webAliasRedirects": "1"
    }
  }' | jq

Remote request:

curl -k -s -X POST https://API-IP:9092/v2/cce   -H "Content-Type: application/json"   -H "X-Client-Secret: CLIENT-SECRET"
  -H "Content-Type: application/json"   -d '{
    "cmd": "CREATE",
    "class": "Vsite",
    "user": "admin",
    "token": "REPLACE_WITH_TOKEN",
    "data": {
      "mailAliases": "",
      "fqdn": "t2.smd.net",
      "mailCatchAll": "",
      "hostname": "t2",
      "ipaddr": "192.168.151.218",
      "ipaddrIPv6": "",
      "userPrefixEnabled": "0",
      "maxusers": "25",
      "volume": "/home",
      "dns_auto": "0",
      "userPrefixField": "",
      "site_preview": "0",
      "createdUser": "admin",
      "emailDisabled": "0",
      "domain": "smd.net",
      "prefix": "",
      "webAliases": "",
      "webAliasRedirects": "1"
    }
  }'

Response (success):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "DATA": {},
    "oidlist": [
      "63"
    ]
  }
}

Response (fail):

{
  "status": 401,
  "message": "GOODBYE",
  "data": {
    "DATA": {},
    "errors": [
      {
        "code": 305,
        "message": "WARN \"[[base-network.ip_restricted,ipaddr=\"192.168.151.218\"]]\""
      },
      {
        "code": 401,
        "message": "FAIL"
      }
    ],
    "oidlist": [
      "63"
    ]
  }
}

DESTROY:

The function DESTROY takes the Object ID (OID) as argument and attempts do "destroy" (remove) the Object in question from CODB. That will also remove all NameSpaces associated with said Object. A DESTROY may fail for several reasons, such as ACLs, the Object ID not existing or dependencies or errors that were raised by Handlers while trying to remove the object. 

Local request:

curl -k -s -X POST https://127.0.0.1:9092/v2/cce
  -H "Content-Type: application/json"
  -d '{
    "cmd": "DESTROY 63",
    "user": "admin",
    "sessionid": "REPLACE_WITH_SESSION_ID",
  }' | jq

Remote request:

curl -k -s -X POST https://API-IP:9092/v2/cce
  -H "Content-Type: application/json"
  -H "X-Client-Secret: CLIENT-SECRET"
  -d '{
    "cmd": "DESTROY 63",
    "user": "admin",
    "token": "REPLACE_WITH_TOKEN",
  }' | jq

Response (success):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "DATA": {}
  }
}

Response (fail):

{
  "status": 401,
  "message": "GOODBYE",
  "data": {
    "DATA": {},
    "errors": [
      {
        "code": 300,
        "message": "UNKNOWN OBJECT 63"
      },
      {
        "code": 401,
        "message": "FAIL"
      }
    ]
  }
}

GETOBJECT:

The command GETOBJECT combines FIND and GET and will return an object that matches the search criteria.

Local request:

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -d '{
  "cmd": "GETOBJECT",
  "class": "Vsite",
  "args": { "name": "site1" },
  "namespace": "",
  "user": "admin",
  "sessionid": "SESSION-ID"
}' | jq

Remote request:

curl -sk -X POST https://API-IP:9092/v2/cce -H "Content-Type: application/json" -H "X-Client-Secret: CLIENT-SECRET" -d '{"cmd": "GETOBJECT", "class": "Vsite", "args": { "name": "site1" }, "token": "TOKEN"}' | jq

Response (success):

{
  "status": 201,
  "message": "OK",
  "data": {
    "DATA": {
      "basedir": "/home/.sites/site1",
      "class": "Vsite",
      "classver": "1.0",
      "createduser": "admin",
      "dns_auto": "1",
      "domain": "smd.net",
      "emaildisabled": "0",
      "force_update": "1747164973",
      "fqdn": "t1.smd.net",
      "hostname": "t1",
      "ipaddr": "208.77.151.218",
      "ipaddripv6": "",
      "mailaliases": "",
      "mailcatchall": "",
      "maxusers": "25",
      "name": "site1",
      "namespace": "",
      "oid": "34",
      "prefix": "",
      "site_preview": "0",
      "siteadmincaps": "",
      "suspend": "0",
      "userprefixenabled": "0",
      "userprefixfield": "",
      "userwebsdisabled": "0",
      "volume": "/home",
      "webaliases": "",
      "webaliasredirects": "1"
    }
  }
}

Response (fail):

{
  "status": 404,
  "message": "Object not found"
}

GETALL:

The command GETALL combines FIND and GET and will return one or more objects that matches the search criteria AND all its NameSpaces. You can search by OIDs (if you know them already), or by specifying arguments.

Local request:

curl -k -s -X POST https://127.0.0.1:9092/v2/cce -d '{
  "cmd": "GETALL",
  "oids": ["56", "58"],
  "args": { "name": "site1" },
  "user": "admin",
  "sessionid": "SESSION-ID"
}' | jq

Remote request:

curl -k -s -X POST https://API-IP:9092/v2/cce -H "Content-Type: application/json" 
  -H "X-Client-Secret: CLIENT-SECRET" -d '{
  "cmd": "GETALL",
  "oids": ["56", "58"],
  "args": { "name": "site1" },
  "token": "TOKEN"
}' | jq

Response (success):

{
  "status": 201,
  "message": "OK",
  "data": {
    "objects": {
      "56": {           // <--- First OID with all NameSpaces
        "Disk": {
          [...]
        },
        "Email": {
          [...]
        },
        "ImapSync": {
          [...]
        },
        "OBJECT": {
          [...]
        },
        "Radicale": {
          [...]
        },
        "RootAccess": {
          [...]
        },
        "SSH": {
          [...]
        },
        "Shell": {
          [...]
        },
        "Sites": {
          [...]
        },
        [...]
      },
      "58": {           // <--- Second OID with all NameSpaces
        "Disk": {
          [...]
        },
        "Email": {
          [...]
        },
        [...]
        "OBJECT": {
          [...]
        },
        "Radicale": {
          [...]
        },
        "RootAccess": {
          [...]
        },
        "SSH": {
          [...]
        },
        "Shell": {
          [...]
        },
        "Sites": {
          [...]
        },
        "subdomains": {
          [...]
        }
      }
    }
  }
}

Response (fail):

{
  "status": 201,
  "message": "GOODBYE",
  "data": {
    "errors": [
      {
        "code": 401,
        "message": "FAIL"
      }
    ],
    "oid": "-1"
  }
}

 

Previous page: API (v2) Find related Next page: API (v2) Classes/Names