Ringfree Node API

Ringfree Node API

Overview

Access API for PBX and Container Management.
Datacenter routes are accessed by means of the reverse proxy set up in that DC. Currently there are only two:

atl.ringfree.biz
dfw.ringfree.biz

To connect with the nodes in that datacenter, you will use the the ‘n##’ designation for that node. For instance, node 1 in ATL would require that you use this url:

atl.ringfree.biz/n01/

and similarly for DFW:

dfw.ringfree.biz/n07/

Access to the storage nodes in the datacenter only requires changing to the ‘s##’ designation, i.e.:

atl.ringfree.biz/s01/
dfw.ringfree.biz/s01/

Below are the available routes on the nodes. For brevity, the route will be shortened to /api/v2/…, with the assumption that the above rules are followed and applied in front of this route, i.e.:

atl.ringfree.biz/n01/api/v2/...

GET Routes:

/api/v2/test

Simple GET test route. Returns JSON enpred ‘200’ response.

  • Expected Return:
    {"status":200,"message":"Success","data":{"gettest":"success"}}

/api/v2/ctid/$ctid/

$ctid here is the actual Container ID. Returns status check for container if it exists on that node.

  • Expected Return (container exists):
    {"status":200,"message":"Success","data":{"CTID":"1900666","NPROC":"6","STATUS":"running","IP_ADDR":"172.16.67.207","HOSTNAME":"butthole.ringfree.biz"}}
  • Expected Return (container does not exist):
    {"status":404,"message":"Container Does Not Exist","data":null}

/api/v2/ctid/$ctid/nimbus

$ctid here is the actual Container ID. Returns status check for container’s Nimbus mount directories. Checks if dir extists and that it’s at least the base/vanilla size.

  • Expected Success Return (Nimbus Ready to Mount):

    {"status":200,"message":"Nimbus Ready for Mount","data":null}

  • Expected Failure Return (Nimbus does not exist):

    {"status":404,"message":"Nimbus Directory Missing","data":null}

  • Expected Failure Return (Nimbus not fully Sync’d):

    {"status":409, "message":"Nimbus Still Syncing","data":null}

POST Routes:

/api/v2/test "action=test"

Simple POST test route. Returns JSON enpred ‘200’ response.

  • Expected Return:
    {"status":200,"message":"Success","data":{"posttest":"success"}}

/api/v2/ctid/$ctid/ "action=$action"

This route manages the container itself. $ctid is the container’s ID and $action what what you are doing to the container. Currently supported actions: ‘create’, ‘start’, ‘stop’, ‘restart’.

  • $action = ‘create’:
    Creates the container. Actual function call changes depending on the type of node. SQL node runs stage 1, Storage Nodes run stage 2 and stage 3, and host node runs stage 4. Create requires 8 other parameters before being able to complete successfully: type, hostname, ip, rootpw, adminpw, subdomain, vendorid, and dbhost.

    • Expected Success Return:
      {"status":200,"message":"Success","data":{"result":"complete"}}
    • Possible Failure Responses:
      • if type parameter does not match sql, stor, nimbus, nor node:
        {"status":400,"message":"Action Type Not Recognized","data":null}
      • if physical node not set up for that type/stage:
        {"status":501,"message":"Not Implemented","data":null}
      • If missing any of the import parameters (message will provide list of missing parameters) and data will be JSON enpred POST parameters provided:
        {"status":400,"message":"Missing Type, Hostname, IP, ...","data": {}}
    • $action = ‘start’:
      Mounts and starts the container on node.

      • Expected Success Return:
        {"status":200,"message":"Success","data":{"result":"Container start in progress..."}}
      • Expected Failure Return:
        {"status":409,"message":"Container Already Running","data":null}
    • $action = ‘stop’:
      Stops and unmounts container on node.

      • Expected Success Return:
        {"status":200,"message":"Success","data":{"result":"Container is unmounted"}}
      • Expected Failure Return:
        {"status":409,"message":"Container already stopped","data":null}
    • $action = ‘restart’:
      Restarts running container on node.

      • Expected Success Return:
        {"status":200,"message":"Success","data":{"result":"Container start in progress..."}}
      • Expected Failure Return:
        {"status":409,"message":"Container Not Running","data":null}

    /api/v2/ctid/$ctid/services/ "action=$action"

    This route is for managing the services running on a container. $ctid is the container’s ID and the $action is how you want the services to change. Currently supported actions: ‘start’, ‘stop’, ‘chown’.

    • $action = ‘start’:
      Starts the services on the container.

      • Expected Success Return:
        {"status":200,"message":"Success","data":{"result":"complete"}}
      • Expected Failure Return:
        {"status":409,"message":"Asterisk already running","data":null}
    • $action = ‘stop’:
      Stops the services on the container.

      • Expected Success Return:
        {"status":200,"message":"Success","data":{"result":"complete"}}
      • Expected Failure Return:
        {"status":409,"message":"Asterisk already stopped","data":null}
    • $action = ‘chown’:
      Sets proper permissions on the container.

      • Expected Success Return:
        {"status":200,"message":"Success","data":{"result":"complete"}}
      • Expected Failure Return:

        Not applicable; Chown should complete regardless of services running or not. If error encountered, likely related to $ctid value and not the $action.