API » History » Revision 11
Revision 10 (Ohad Levy, 11/11/2010 10:16 AM) → Revision 11/45 (Justin Sherrill, 02/21/2011 12:55 PM)
h1. API
*NOTE*: Version of 0.1-6 or git develop branch are required to use the API
Foreman 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 API.
Examples below are either via curl or ruby rest_client
most pages can be browsed via adding the format option to the url (at least for get requests), i.e.
<pre>
http://foreman/environemnts?format=json
</pre>
Or using HTTP Headers
<pre>
curl -H "Content-Type:application/json" -H "Accept:application/json" http://foreman/hosts
</pre>
Output is JSON formatted, in the last example expect a similar output:
<pre>
[{"host":{"name":"pm1.local.net"}},{"host":{"name":"pm2.local.net"}}....]
</pre>
h2. List of API's
|_.Path|_.REST Type|_.Example JSON| Type|_.Description|
|/roles/ID|DELETE|{role:{"name":string}}|
|/roles|POST|{role:{"builtin":string, "name":string, "permissions":string}}|
|/roles|GET|
|/roles/ID|PUT|{role:{"builtin":string, "name":string, "permissions":string}}|
| |
|/factvalues|POST|{factvalue:{"fact_name_id":int, "host_id":int, "value":string}}|
|/factvalues|GET|
| |
|/environments/ID|DELETE|{environment:{"name":string}}|
|/environments|POST|{environment:{"name":string}}|
|/environments|GET|
|/environments/ID|PUT|{environment:{"name":string}}|
| |
|/operatingsystems/ID|DELETE|{operatingsystem:{"name":string}}|
|/operatingsystems|POST|{operatingsystem:{"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}|
|/operatingsystems|GET|
|/operatingsystems/ID|PUT|{operatingsystem:{"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}|
| |
|/hostgroups/ID|DELETE|{hostgroup:{"name":string}}|
|/hostgroups|POST|{hostgroup:{"architecture_id":int, "environment_id":int, "medium_id":int, "name":string, "operatingsystem_id":int, "ptable_id":int, "puppetmaster":string, "root_pass":string}}|
|/hostgroups|GET|
|/hostgroups/ID|PUT|{hostgroup:{"architecture_id":int, "environment_id":int, "medium_id":int, "name":string, "operatingsystem_id":int, "ptable_id":int, "puppetmaster":string, "root_pass":string}}|
| |
|/ptables/ID|DELETE|{ptable:{"name":string}}|
|/ptables|POST|{ptable:{"layout":string, "name":string, "operatingsystem_id":int}}|
|/ptables|GET|
|/ptables/ID|PUT|{ptable:{"layout":string, "name":string, "operatingsystem_id":int}}|
| |
|/authsourceldaps/ID|DELETE|{authsourceldap:{"name":string}}|
|/authsourceldaps|POST|{authsourceldap:{"account":string, "account_password":string, "attr_firstname":string, "attr_lastname":string, "attr_login":string, "attr_mail":string, "base_dn":string, "host":string, "name":string, "onthefly_register":string, "port":string, "tls":string, "type":string}}|
|/authsourceldaps|GET|
|/authsourceldaps/ID|PUT|{authsourceldap:{"account":string, "account_password":string, "attr_firstname":string, "attr_lastname":string, "attr_login":string, "attr_mail":string, "base_dn":string, "host":string, "name":string, "onthefly_register":string, "port":string, "tls":string, "type":string}}|
| |
|/domains/ID|DELETE|{domain:{"name":string}}|
|/domains|POST|{domain:{"dns_id":int, "fullname":string, "name":string}}|
|/domains|GET|
|/domains/ID|PUT|{domain:{"dns_id":int, "fullname":string, "name":string}}|
| |
|/puppetclasses/ID|DELETE|{puppetclass:{"name":string}}|
|/puppetclasses|POST|{puppetclass:{"name":string, "nameindicator":string, "operatingsystem_id":int}}|
|/puppetclasses|GET|
|/puppetclasses/ID|PUT|{puppetclass:{"name":string, "nameindicator":string, "operatingsystem_id":int}}|
| |
|/hypervisors/ID|DELETE|{hypervisor:{"name":string}}|
|/hypervisors|POST|{hypervisor:{"kind":string, "name":string, "uri":string}}|
|/hypervisors|GET|
|/hypervisors/ID|PUT|{hypervisor:{"kind":string, "name":string, "uri":string}}|
| |
|/models/ID|DELETE|{model:{"name":string}}|
|/models|POST|{model:{"info":string, "name":string}}|
|/models|GET|
|/models/ID|PUT|{model:{"info":string, "name":string}}|
| |
|/usergroups/ID|DELETE|{usergroup:{"name":string}}|
|/usergroups|POST|{usergroup:{"name":string}}|
|/usergroups|GET|
|/usergroups/ID|PUT|{usergroup:{"name":string}}|
| |
|/reports/ID|DELETE|{report:{}}|
|/reports|POST|{report:{"host_id":int, "metrics":string, "reported_at":string, "status":string}}|
|/reports|GET|
| |
|/configtemplates/ID|DELETE|{configtemplate:{"name":string}}|
|/configtemplates|POST|{configtemplate:{"hostgroup_id":int, "name":string, "snippet":string, "template":string, "template_kind_id":int}}|
|/configtemplates|GET|
|/configtemplates/ID|PUT|{configtemplate:{"hostgroup_id":int, "name":string, "snippet":string, "template":string, "template_kind_id":int}}|
| |
|/commonparameters/ID|DELETE|{commonparameter:{"name":string}}|
|/commonparameters|POST|{commonparameter:{"name":string, "reference_id":int, "type":string, "value":string}}|
|/commonparameters|GET|
|/commonparameters/ID|PUT|{commonparameter:{"name":string, "reference_id":int, "type":string, "value":string}}|
| |
|/users/ID|DELETE|{user:{}}|
|/users|POST|{user:{"admin":string, "auth_source_id":int, "domains_andor":string, "facts_andor":string, "filter_on_owner":string, "firstname":string, "hostgroups_andor":string, "last_login_on":string, "lastname":string, "login":string, "mail":string, "password_hash":string, "password_salt":string, "role_id":int}}|
|/users|GET|
|/users/ID|PUT|{user:{"admin":string, "auth_source_id":int, "domains_andor":string, "facts_andor":string, "filter_on_owner":string, "firstname":string, "hostgroups_andor":string, "last_login_on":string, "lastname":string, "login":string, "mail":string, "password_hash":string, "password_salt":string, "role_id":int}}|
| |
|/architectures/ID|DELETE|{architecture:{"name":string}}|
|/architectures|POST|{architecture:{"name":string}}|
|/architectures|GET|
|/architectures/ID|PUT|{architecture:{"name":string}}|
| |
|/media/ID|DELETE|{medium:{"name":string}}|
|/media|POST|{medium:{"name":string, "path":string}}|
|/media|GET|
|/media/ID|PUT|{medium:{"name":string, "path":string}}|
| |
|/hosts/fqdn|DELETE|{host:{"name":string}}|
|/hosts|POST|{host:{"architecture_id":int, "build":string, "comment":string, "disk":string, "domain_id":int, "enabled":string, "environment":string, "environment_id":int, "hostgroup_id":int, "installed_at":string, "ip":string, "last_compile":string, "last_freshcheck":string, "last_report":string, "mac":string, "medium_id":int, "model_id":int, "name":string, "operatingsystem_id":int, "owner_id":int, "owner_type":string, "ptable_id":int, "puppet_status":string, "puppetmaster":string, "root_pass":string, "serial":string, "source_file_id":int, "sp_ip":string, "sp_mac":string, "sp_name":string, "sp_subnet_id":int, "subnet_id":int}}|
|/hosts|GET|
|/hosts/fqdn|PUT|{host:{"architecture_id":int, "build":string, "comment":string, "disk":string, "domain_id":int, "enabled":string, "environment":string, "environment_id":int, "hostgroup_id":int, "installed_at":string, "ip":string, "last_compile":string, "last_freshcheck":string, "last_report":string, "mac":string, "medium_id":int, "model_id":int, "name":string, "operatingsystem_id":int, "owner_id":int, "owner_type":string, "ptable_id":int, "puppet_status":string, "puppetmaster":string, "root_pass":string, "serial":string, "source_file_id":int, "sp_ip":string, "sp_mac":string, "sp_name":string, "sp_subnet_id":int, "subnet_id":int}}|
| |
|/subnets/ID|DELETE|{subnet:{"name":string}}|
|/subnets|POST|{subnet:{"dhcp_id":int, "domain_id":int, "mask":string, "name":string, "network":string, "priority":string, "ranges":string, "tftp_id":int, "vlanid":int}}|
|/subnets|GET|
|/subnets/ID|PUT|{subnet:{"dhcp_id":int, "domain_id":int, "mask":string, "name":string, "network":string, "priority":string, "ranges":string, "tftp_id":int, "vlanid":int}}|
| |
|/smartproxies/ID|DELETE|{smartproxy:{"name":string}}|
|/smartproxies|POST|{smartproxy:{"name":string, "url":string}}|
|/smartproxies|GET|
|/smartproxies/ID|PUT|{smartproxy:{"name":string, "url":string}}|
| |
|/lookupkeys/ID|DELETE|{lookupkey:{}}|
|/lookupkeys|POST|{lookupkey:{"key":string}}|
|/lookupkeys|GET|
|/lookupkeys/ID|PUT|{lookupkey:{"key":string}}|
| |
|/architectures|GET|List of valid OS Architectures(name and ID)|
|/architectures/x86_64|GET|Description of the x86_64 Architecture (name and ID)|
|/dashboard|GET|Summary statistcs (total hosts, active hosts, hosts in error etc)|
|/domains|GET|List of known domains (name and ID)|
|/domains/my_domain|GET|Description of "my_domain" (name and ID)|
|/environments|GET|List of known environments (name and ID)|
|/environments/production|GET|Description of the "production" (name and ID and associated host list)|
|/fact_values|GET|List of known Facts (value, name and host)|
|/hostgroups|GET|List of known hostgroups (name and ID)|
|/hostgroups/common|GET|Description of "common" (name and ID)|
|/hosts|GET|List of known hosts (only name)|
|/hosts/errors|GET|List of hosts in error state(only name)|
|/hosts/active|GET|List of active hosts(only name)|
|/hosts/out_of_sync|GET|List of out of sync hosts(only name)|
|/hosts/disabled|GET|List of disabled hosts(only name)|
|/hosts|POST|creates a new host, 201 return sucesful creation, otherwise the errors will be returned|
|/hosts/fqdn|GET|Host Attributes (name, usergroup, last_report, os properties...)|
|/hosts/fqdn|DELETE|Removes the host "fqdn"|
|/hosts/fqdn/setBuild|GET| Enable Host for (re-)build |
|/hosts/fqdn/facts|GET| Returns host facts|
|/hosts/fqdn/pxe_config|GET| Returns syslinux configuration file for fqdn|
|/medias|GET|List of known mediums (name and ID)|
|/medias/1|GET|Description of media which ID is 1 (name and ID and path/url)|
|/operatingsystems|GET|List of known operating systems (Release name, ID and allowed mediums, architectures and partition tables)|
|/operatingsystems/1|GET| Description of operating systems which its ID is 1 (Release name, ID and allowed mediums, architectures and partition tables)|
|/operatingsystems/1/bootfiles?media=<media_name>&architecture=x86_64|GET| tftp boot files and their respective urls (where they can be found)|
|/ptables|GET|List of known Partition tables (name and ID)|
|/ptables/1|GET|Description of Partition table which its ID is 1 (name and ID)|
|/puppetclasses|GET|a hash of known Puppetclasses orginazined by module name (module => {:class1, :class2})|
Please raise a new issue if you need additional API's