Project

General

Profile

API » History » Revision 13

Revision 12 (Justin Sherrill, 02/21/2011 01:27 PM) → Revision 13/45 (Justin Sherrill, 02/21/2011 01:39 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|_.Description|_.Example Input JSON|   
 |_.Architecture | 
 |/architectures|POST|Create |/roles/false|DELETE|Delete a new Architecture|{architecture Role|{role : {"name":string}}| 
 |/architectures/false|DELETE|Delete |/roles|POST|Create a Architecture|{architecture : {"name":string}}| 
 |/architectures|GET|Retrieve a list of Architectures| 
 |/architectures/false|PUT|Update an existing Architecture|{architecture : {"name":string}}| 
 |_.AuthSourceLdap | 
 |/authsourceldaps|POST|Create a new Auth source ldap|{authsourceldap Role|{role : {"account":string, "account_password":string, "attr_firstname":string, "attr_lastname":string, "attr_login":string, "attr_mail":string, "base_dn":string, "host":string, {"builtin":string, "name":string, "onthefly_register":string, "port":string, "tls":string, "type":string}}| "permissions":string}}| 
 |/authsourceldaps/false|DELETE|Delete |/roles|GET|Retrieve a Auth source ldap|{authsourceldap : {"name":string}}| 
 |/authsourceldaps|GET|Retrieve a list of Auth source ldaps| Roles| 
 |/authsourceldaps/false|PUT|Update |/roles/false|PUT|Update an existing Auth source ldap|{authsourceldap Role|{role : {"account":string, "account_password":string, "attr_firstname":string, "attr_lastname":string, "attr_login":string, "attr_mail":string, "base_dn":string, "host":string, {"builtin":string, "name":string, "onthefly_register":string, "port":string, "tls":string, "type":string}}| "permissions":string}}| 
 |_.CommonParameter | | 
 |/commonparameters|POST|Create |/factvalues|POST|Create a new Common parameter|{commonparameter Fact value|{factvalue : {"name":string, "reference_id":int, "type":string, {"fact_name_id":int, "host_id":int, "value":string}}| 
 |/commonparameters/false|DELETE|Delete |/factvalues|GET|Retrieve a Common parameter|{commonparameter : {"name":string}}| 
 |/commonparameters|GET|Retrieve a list of Common parameters| Fact values| 
 |/commonparameters/false|PUT|Update an existing Common parameter|{commonparameter : {"name":string, "reference_id":int, "type":string, "value":string}}| 
 |_.ConfigTemplate | | 
 |/configtemplates|POST|Create |/environments/false|DELETE|Delete a new Config template|{configtemplate Environment|{environment : {"hostgroup_id":int, "name":string, "snippet":string, "template":string, "template_kind_id":int}}| 
 |/configtemplates/false|DELETE|Delete a Config template|{configtemplate : {"name":string}}| 
 |/configtemplates|GET|Retrieve |/environments|POST|Create a list of Config templates| 
 |/configtemplates/false|PUT|Update an existing Config template|{configtemplate : {"hostgroup_id":int, "name":string, "snippet":string, "template":string, "template_kind_id":int}}| 
 |_.Domain | 
 |/domains|POST|Create a new Domain|{domain Environment|{environment : {"dns_id":int, "fullname":string, "name":string}}| 
 |/domains/false|DELETE|Delete a Domain|{domain : {"name":string}}| 
 |/domains|GET|Retrieve |/environments|GET|Retrieve a list of Domains| Environments| 
 |/domains/false|PUT|Update |/environments/false|PUT|Update an existing Domain|{domain Environment|{environment : {"dns_id":int, "fullname":string, "name":string}}| {"name":string}}| 
 |_.Environment | | 
 |/environments|POST|Create |/operatingsystems/false|DELETE|Delete a new Environment|{environment Operatingsystem|{operatingsystem : {"name":string}}| 
 |/environments/false|DELETE|Delete |/operatingsystems|POST|Create a Environment|{environment new Operatingsystem|{operatingsystem : {"name":string}}| {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}| 
 |/environments|GET|Retrieve |/operatingsystems|GET|Retrieve a list of Environments| Operatingsystems| 
 |/environments/false|PUT|Update |/operatingsystems/false|PUT|Update an existing Environment|{environment Operatingsystem|{operatingsystem : {"name":string}}| {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}| 
 |_.FactValue | | 
 |/factvalues|POST|Create |/hostgroups/false|DELETE|Delete a new Fact value|{factvalue Hostgroup|{hostgroup : {"fact_name_id":int, "host_id":int, "value":string}}| {"name":string}}| 
 |/factvalues|GET|Retrieve a list of Fact values| 
 |_.Hostgroup | 
 |/hostgroups|POST|Create a new Hostgroup|{hostgroup : {"architecture_id":int, "environment_id":int, "medium_id":int, "name":string, "operatingsystem_id":int, "ptable_id":int, "puppetmaster":string, "root_pass":string}}| 
 |/hostgroups/false|DELETE|Delete a Hostgroup|{hostgroup : {"name":string}}| 
 |/hostgroups|GET|Retrieve a list of Hostgroups| 
 |/hostgroups/false|PUT|Update an existing Hostgroup|{hostgroup : {"architecture_id":int, "environment_id":int, "medium_id":int, "name":string, "operatingsystem_id":int, "ptable_id":int, "puppetmaster":string, "root_pass":string}}| 
 |_.Host | | 
 |/hosts|POST|Create |/ptables/false|DELETE|Delete a new Host|{host Ptable|{ptable : {"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}}| {"name":string}}| 
 |/hosts/false|DELETE|Delete |/ptables|POST|Create a Host|{host new Ptable|{ptable : {"name":string}}| {"layout":string, "name":string, "operatingsystem_id":int}}| 
 |/hosts|GET|Retrieve |/ptables|GET|Retrieve a list of Hosts| Ptables| 
 |/hosts/false|PUT|Update |/ptables/false|PUT|Update an existing Host|{host Ptable|{ptable : {"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, {"layout":string, "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}}| "operatingsystem_id":int}}| 
 |_.Hypervisor | | 
 |/hypervisors|POST|Create |/authsourceldaps/false|DELETE|Delete a new Hypervisor|{hypervisor Auth source ldap|{authsourceldap : {"kind":string, "name":string, "uri":string}}| {"name":string}}| 
 |/hypervisors/false|DELETE|Delete |/authsourceldaps|POST|Create a Hypervisor|{hypervisor new Auth source ldap|{authsourceldap : {"name":string}}| {"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}}| 
 |/hypervisors|GET|Retrieve |/authsourceldaps|GET|Retrieve a list of Hypervisors| Auth source ldaps| 
 |/hypervisors/false|PUT|Update |/authsourceldaps/false|PUT|Update an existing Hypervisor|{hypervisor Auth source ldap|{authsourceldap : {"kind":string, {"account":string, "account_password":string, "attr_firstname":string, "attr_lastname":string, "attr_login":string, "attr_mail":string, "base_dn":string, "host":string, "name":string, "uri":string}}| "onthefly_register":string, "port":string, "tls":string, "type":string}}| 
 |_.LookupKey | | 
 |/lookupkeys|POST|Create |/domains/false|DELETE|Delete a new Lookup key|{lookupkey Domain|{domain : {"key":string}}| {"name":string}}| 
 |/lookupkeys/false|DELETE|Delete |/domains|POST|Create a Lookup key|{lookupkey new Domain|{domain : {}}| {"dns_id":int, "fullname":string, "name":string}}| 
 |/lookupkeys|GET|Retrieve |/domains|GET|Retrieve a list of Lookup keys| Domains| 
 |/lookupkeys/false|PUT|Update |/domains/false|PUT|Update an existing Lookup key|{lookupkey Domain|{domain : {"key":string}}| {"dns_id":int, "fullname":string, "name":string}}| 
 |_.Medium | | 
 |/media|POST|Create |/puppetclasses/false|DELETE|Delete a Puppetclass|{puppetclass : {"name":string}}| 
 |/puppetclasses|POST|Create a new Medium|{medium Puppetclass|{puppetclass : {"name":string, "path":string}}| "nameindicator":string, "operatingsystem_id":int}}| 
 |/media/false|DELETE|Delete |/puppetclasses|GET|Retrieve a Medium|{medium list of Puppetclasses| 
 |/puppetclasses/false|PUT|Update an existing Puppetclass|{puppetclass : {"name":string, "nameindicator":string, "operatingsystem_id":int}}| 
 | | 
 |/hypervisors/false|DELETE|Delete a Hypervisor|{hypervisor : {"name":string}}| 
 |/media|GET|Retrieve |/hypervisors|POST|Create a new Hypervisor|{hypervisor : {"kind":string, "name":string, "uri":string}}| 
 |/hypervisors|GET|Retrieve a list of Media| Hypervisors| 
 |/media/false|PUT|Update |/hypervisors/false|PUT|Update an existing Medium|{medium Hypervisor|{hypervisor : {"name":string, "path":string}}| {"kind":string, "name":string, "uri":string}}| 
 |_.Model | | 
 |/models/false|DELETE|Delete a Model|{model : {"name":string}}| 
 |/models|POST|Create a new Model|{model : {"info":string, "name":string}}| 
 |/models/false|DELETE|Delete a Model|{model : {"name":string}}| 
 |/models|GET|Retrieve a list of Models| 
 |/models/false|PUT|Update an existing Model|{model : {"info":string, "name":string}}| 
 |_.Operatingsystem | | 
 |/operatingsystems|POST|Create |/usergroups/false|DELETE|Delete a new Operatingsystem|{operatingsystem Usergroup|{usergroup : {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}| {"name":string}}| 
 |/operatingsystems/false|DELETE|Delete |/usergroups|POST|Create a Operatingsystem|{operatingsystem new Usergroup|{usergroup : {"name":string}}| 
 |/operatingsystems|GET|Retrieve |/usergroups|GET|Retrieve a list of Operatingsystems| Usergroups| 
 |/operatingsystems/false|PUT|Update |/usergroups/false|PUT|Update an existing Operatingsystem|{operatingsystem Usergroup|{usergroup : {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}| {"name":string}}| 
 |_.Ptable | | 
 |/ptables|POST|Create |/reports/false|DELETE|Delete a Report|{report : {}}| 
 |/reports|POST|Create a new Ptable|{ptable Report|{report : {"layout":string, "name":string, "operatingsystem_id":int}}| {"host_id":int, "metrics":string, "reported_at":string, "status":string}}| 
 |/ptables/false|DELETE|Delete |/reports|GET|Retrieve a Ptable|{ptable list of Reports| 
 | | 
 |/configtemplates/false|DELETE|Delete a Config template|{configtemplate : {"name":string}}| 
 |/ptables|GET|Retrieve |/configtemplates|POST|Create a new Config template|{configtemplate : {"hostgroup_id":int, "name":string, "snippet":string, "template":string, "template_kind_id":int}}| 
 |/configtemplates|GET|Retrieve a list of Ptables| Config templates| 
 |/ptables/false|PUT|Update |/configtemplates/false|PUT|Update an existing Ptable|{ptable Config template|{configtemplate : {"layout":string, {"hostgroup_id":int, "name":string, "operatingsystem_id":int}}| "snippet":string, "template":string, "template_kind_id":int}}| 
 |_.Puppetclass | | 
 |/puppetclasses|POST|Create |/commonparameters/false|DELETE|Delete a new Puppetclass|{puppetclass Common parameter|{commonparameter : {"name":string, "nameindicator":string, "operatingsystem_id":int}}| {"name":string}}| 
 |/puppetclasses/false|DELETE|Delete |/commonparameters|POST|Create a Puppetclass|{puppetclass new Common parameter|{commonparameter : {"name":string}}| {"name":string, "reference_id":int, "type":string, "value":string}}| 
 |/puppetclasses|GET|Retrieve |/commonparameters|GET|Retrieve a list of Puppetclasses| Common parameters| 
 |/puppetclasses/false|PUT|Update |/commonparameters/false|PUT|Update an existing Puppetclass|{puppetclass Common parameter|{commonparameter : {"name":string, "nameindicator":string, "operatingsystem_id":int}}| "reference_id":int, "type":string, "value":string}}| 
 |_.Report | | 
 |/reports|POST|Create |/users/false|DELETE|Delete a new Report|{report User|{user : {"host_id":int, "metrics":string, "reported_at":string, "status":string}}| {}}| 
 |/reports/false|DELETE|Delete |/users|POST|Create a Report|{report new User|{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}}| 
 |/reports|GET|Retrieve |/users|GET|Retrieve a list of Reports| Users| 
 |_.Role |/users/false|PUT|Update an existing User|{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}}| 
 | | 
 |/roles|POST|Create |/architectures/false|DELETE|Delete a new Role|{role Architecture|{architecture : {"builtin":string, "name":string, "permissions":string}}| {"name":string}}| 
 |/roles/false|DELETE|Delete |/architectures|POST|Create a Role|{role new Architecture|{architecture : {"name":string}}| 
 |/roles|GET|Retrieve |/architectures|GET|Retrieve a list of Roles| Architectures| 
 |/roles/false|PUT|Update |/architectures/false|PUT|Update an existing Role|{role Architecture|{architecture : {"builtin":string, "name":string, "permissions":string}}| {"name":string}}| 
 |_.SmartProxy | | 
 |/smartproxies|POST|Create |/media/false|DELETE|Delete a Medium|{medium : {"name":string}}| 
 |/media|POST|Create a new Smart proxy|{smartproxy Medium|{medium : {"name":string, "url":string}}| "path":string}}| 
 |/smartproxies/false|DELETE|Delete |/media|GET|Retrieve a Smart proxy|{smartproxy list of Media| 
 |/media/false|PUT|Update an existing Medium|{medium : {"name":string, "path":string}}| 
 | | 
 |/hosts/false|DELETE|Delete a Host|{host : {"name":string}}| 
 |/smartproxies|GET|Retrieve |/hosts|POST|Create a new Host|{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|Retrieve a list of Smart proxies| Hosts| 
 |/smartproxies/false|PUT|Update |/hosts/false|PUT|Update an existing Smart proxy|{smartproxy Host|{host : {"name":string, "url":string}}| {"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}}| 
 |_.Subnet | | 
 |/subnets/false|DELETE|Delete a Subnet|{subnet : {"name":string}}| 
 |/subnets|POST|Create a new Subnet|{subnet : {"dhcp_id":int, "domain_id":int, "mask":string, "name":string, "network":string, "priority":string, "ranges":string, "tftp_id":int, "vlanid":int}}| 
 |/subnets/false|DELETE|Delete a Subnet|{subnet : {"name":string}}| 
 |/subnets|GET|Retrieve a list of Subnets| 
 |/subnets/false|PUT|Update an existing Subnet|{subnet : {"dhcp_id":int, "domain_id":int, "mask":string, "name":string, "network":string, "priority":string, "ranges":string, "tftp_id":int, "vlanid":int}}| 
 |_.Usergroup | | 
 |/usergroups|POST|Create |/smartproxies/false|DELETE|Delete a new Usergroup|{usergroup Smart proxy|{smartproxy : {"name":string}}| 
 |/usergroups/false|DELETE|Delete |/smartproxies|POST|Create a Usergroup|{usergroup new Smart proxy|{smartproxy : {"name":string}}| {"name":string, "url":string}}| 
 |/usergroups|GET|Retrieve |/smartproxies|GET|Retrieve a list of Usergroups| Smart proxies| 
 |/usergroups/false|PUT|Update |/smartproxies/false|PUT|Update an existing Usergroup|{usergroup Smart proxy|{smartproxy : {"name":string}}| {"name":string, "url":string}}| 
 |_.User | | 
 |/users|POST|Create |/lookupkeys/false|DELETE|Delete a new User|{user Lookup key|{lookupkey : {"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/false|DELETE|Delete |/lookupkeys|POST|Create a User|{user new Lookup key|{lookupkey : {}}| {"key":string}}| 
 |/users|GET|Retrieve |/lookupkeys|GET|Retrieve a list of Users| Lookup keys| 
 |/users/false|PUT|Update |/lookupkeys/false|PUT|Update an existing User|{user Lookup key|{lookupkey : {"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}}| 












 {"key":string}}| 
 | | 











 |/dashboard|GET|Summary statistcs (total hosts, active hosts, hosts in error etc)| 
 |/fact_values|GET|List of known Facts (value, name and host)| 
 |/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/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| 
 |/operatingsystems/1/bootfiles?media=<media_name>&architecture=x86_64|GET| tftp boot files and their respective urls (where they can be found)| 
 |/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