Rest endpoint

To rest or not to rest

Well. ONA doesn't actually have a rest endpoint. This system is old enough that rest endpoints were only just beginning. However, we knew way back then that things should work in a particular way, and we happened to invent our own layout that just happens to be reasonably similar to rest.

So, while ONA does not actually have a rest endpoint, you can interact with ONA in a way that should be mostly functional. To that end, there was always the dcm.pl CLI interface. It was intended to interact with ONA from the CLI or other scripts.

With that said, here are a few examples of how you can use the dcm endpoint to just interact with ONA using curl. NOTE: This requires you to be on v19.0.0 or above.

Curl examples

The basic dcm.php endpoint.. this would be the main URL path for everything. http://localhost/ona/dcm.php

# curl -s "http://localhost/ona/dcm.php"

1
ERROR => No module specified!

The first line, in this case 1 is the exit code. The remaining lines are the textual output from the endpoint. In this case it is complaining that you have not specified a module. Well, how do I know what modules are available to me? Lets ask.

# curl -s "http://localhost/ona/dcm.php?module=get_module_list&type=string

This will return a list of all the possible modules and a short description. Lets call domain_display as an example.

# curl -s "http://localhost/ona/dcm.php?module=domain_display"

101

domain_display-v1.02
Displays an domain record from the database

  Synopsis: domain_display [KEY=VALUE] ...

  Required:
    domain=NAME or ID      domain name or ID of the domain to display

As you can see, it returns a usage statement with a description and required or optional inputs.

Now lets go ahead invoke this module to get the results

# curl -s "http://localhost/ona/dcm.php?module=domain_display&domain=example.com"
0
DOMAIN RECORD (example.com)

    PARENT:     0
    PRIMARY:    testserver.example.com
    ADMIN:      hostmaster
    REFRESH:    86400
    RETRY:      3600
    EXPIRY:     3600
    MINIMUM:    3600

This displays a human readable output. So lets tell it we want json format (you can also do yaml if desired).

#  curl -s "http://localhost/ona/dcm.php?module=domain_display&domain=example.com&format=json"|jq .
{
  "admin_email": "hostmaster",
  "ctime": "2023-05-30 00:30:18",
  "default_ttl": "86400",
  "expiry": "3600",
  "fqdn": "example.com",
  "id": "1",
  "minimum": "3600",
  "module_exit_status": 0,
  "name": "example.com",
  "parent_id": "0",
  "primary_master": "testserver.example.com",
  "refresh": "86400",
  "retry": "3600",
  "serial": "0"
}

Ok lets try and add a new domain

curl -s "http://localhost/ona/dcm.php?module=domain_add&domain=new.example.com&format=json"|jq .
{
  "module_exit_status": 101,
  "module_exit_message": "\ndomain_add-v1.08\nAdds a DNS domain into the database\n\n  Synopsis: domain_add [KEY=VALUE] ...\n\n  Required:\n    name=STRING                             full name of new domain\n                                            (i.e. name.something.com)\n\n  Optional:\n    admin=STRING                            Default (hostmaster)\n    primary_master=STRING                   Default ()\n    refresh=NUMBER                          Default (86400)\n    retry=NUMBER                            Default (3600)\n    expiry=NUMBER                           Default (3600)\n    minimum=NUMBER                          Default (3600)\n    parent=DOMAIN_NAME                      Default ()\n    ttl=NUMBER                              Default (86400)\n\n"
}

Well, that didn't work. You can see the module_exit_message gave us the usage dialog again. This is indicating that we did not provide all the required fields. Lets add a little bit of cleanup of the json output.

# curl -s "http://localhost/ona/dcm.php?module=domain_add&domain=new.example.com&format=json"|jq -r .module_exit_message

domain_add-v1.08
Adds a DNS domain into the database

  Synopsis: domain_add [KEY=VALUE] ...

  Required:
    name=STRING                             full name of new domain
                                            (i.e. name.something.com)

  Optional:
    admin=STRING                            Default (hostmaster)
    primary_master=STRING                   Default ()
    refresh=NUMBER                          Default (86400)
    retry=NUMBER                            Default (3600)
    expiry=NUMBER                           Default (3600)
    minimum=NUMBER                          Default (3600)
    parent=DOMAIN_NAME                      Default ()
    ttl=NUMBER                              Default (86400)

That looks a lot better. Ok so we are missing the required name option. Lets add that to the request by changing the incorrectly named domain filed.

# curl -s "http://localhost/ona/dcm.php?module=domain_add&name=new.example.com&format=json"|jq -r .module_exit_message
Permission denied!

Well, you didn't think we would just let you add things without authenticating did you?

Well no worries, you can simply use basic auth methods with curl.

# curl -u admin -s "http://localhost/ona/dcm.php?module=domain_add&name=new.example.com&format=json"|jq -r .module_exit_message
Enter host password for user 'admin':
INFO => Domain ADDED: new.example.com

Now this is where things really diverge from a standard Rest endpoint. You did add the domain, and it said as much. It just didnt tell you any of the json details you might be expecting. Well, you can now go back and do a domain_display on your new record to get a json record that contains what you probably wanted.

Note, there are no real list functions to query or list many records. Those may come in the future. Maybe you can use ona_sql. Yuck.