Foreman » Smart Proxy

h1. API

Foreman Smart Proxy provides a "REST":http://en.wikipedia.org/wiki/Representational_State_Transfer API, communicating via JSON.

Please refer to this document for latest information about Foreman Smart Proxy API.

h2. List of API's

|_.Path|_.REST Type|_.Description|_.Example Input JSON|  

|_.FEATURES |

|/features|GET|List of features supported by the proxy||

|_.DHCP |

|/dhcp|GET|Retrieve a list of subnets||

|/dhcp/10.1.2.0|GET|Retrieve 10.1.2.0 subnets records||

|/dhcp/10.1.2.0/10.1.2.5|GET|Retrieve 10.1.2.5 reservation information ||

|/dhcp/10.1.2.0/unused_ip|GET|Provides an unused ip address in 10.1.2.0 subnet ||

|/dhcp/10.1.2.0|POST|creates new reservation in 10.1.2.0 subnet |@{"hostname":string, "name":string, "filename":string, "ip":string, "nextserver":string, "mac":string}@|

|/dhcp/10.1.2.0/10.1.2.5|DELETE|Deletes 10.1.2.5 reservation from 10.1.2.0 subnet||

|_.DNS |

|/dns|POST|Create a new DNS record|@{"fqdn":string(name/ip), "value":string(ip/reverse), "type":string(A/PTR)}@|

|/dns/value|DELETE|remove value(ip or reverse) DNS record||

|_.TFTP |

|/tftp/00:11:22:33:44:55|POST|creates pxelinux configuration file for host with MAC address 00:11:22:33:44:55|@{"syslinux_config":string}@|

|/tftp/00:11:22:33:44:55|DELETE|remove pxelinux configuration file for host with MAC address 00:11:22:33:44:55||

|/tftp/create_default|POST|creates a default pxelinux configuration file|@{"syslinux_config":string}@|

|/tftp/fetch_boot_file|POST|creates a default pxelinux configuration file|@{"prefix":string, "path":string}@|

|/tftp/serverName|GET|fetches the TFTP server name to be used within a dhcp record||

|_.PUPPET CA |

|/puppet/ca|GET| list of all puppet certificates ||

|/puppet/ca/certname|POST| Sign pending certificate request ||

|/puppet/ca/certname|DELETE| Remove (clean) and revoke a certificate ||

|/puppet/ca/autosign|GET| list of all puppet autosign entires ||

|/puppet/ca/autosign/certname|POST| Add certname to Puppet autosign ||

|/puppet/ca/autosign/certname|DELETE| Remove certname from Puppet autosign ||

|_.PUPPET |

|/puppet/run|POST| Trigger puppet run / kick|@["hostA", "hostB"]@|

Please raise a new issue if you need additional API's

h2. Manually Calling the API

The API can be manually tested out using curl.  GET types can be retrieved like any other URL.  This one, for example, will return the HTML formatted page with the list of features enabled on the proxy.

<pre>

curl http://localhost:8443/features

</pre>

POST URLs, used to create objects or trigger actions, need to have the parameters passed in via the -d argument.  This curl command line will trigger a puppetrun on server.example.com.

<pre>

curl -d 'nodes=server.example.com' http://localhost:8443/puppet/run

</pre>

Multiple post options may be specified by repeating the -d argument.

<pre>

curl -d 'prefix=boot/CentOS-5-x86_64' -d 'path=http://yourlocalmirrorhere/pub/centos/5/os/x86_64/images/pxeboot/vmlinuz'  http://localhost:8443/tftp/fetch_boot_file

</pre>

When you are creating an object, the identifier for the object is typically passed in as part of the URL, rather than as a POST value.  For example, this will create a PXE boot configuration file for a host with MAC address 00:11:22:33:44:55, and will just put "Hello World" as the contents of the file.  (A real world example would, of course, substitute a valid PXE boot configuration in the string.)

<pre>

curl -d 'syslinux_config=Hello World' http://localhost:8443/tftp/00:11:22:33:44:55

</pre>

In order to delete objects, you use the same URL as in the original creation, but pass it not POST values, and use the DELETE HTTP method instead of POST.  This will delete the PXE boot configuration file created above.

<pre>

curl -X DELETE http://localhost:8443/tftp/00:11:22:33:44:55

</pre>

[[Draft 2.0 version of DNS API]]