Project

General

Profile

API » History » Revision 41

Revision 40 (Petr Chalupa, 10/27/2012 07:58 AM) → Revision 41/45 (Dominic Cleal, 03/19/2013 04:39 AM)

h1. API 

 h2. Foreman 1.1 API 

 The documentation previously held on this page has been incorporated into *NOTE*: Version of 0.1-6 or git develop branch are required to use the main "theforeman.org":http://theforeman.org/ web site.    You can access it here: 

 * "*Foreman API documentation*":http://theforeman.org/api.html 

 *NOTE*: Starting with Foreman 1.1 API documentation can be is auto generated on your installation using @rake apipie:static@, then generated, access using /apidoc on your foreman instance. 
 Auto generated Ruby binding and CLI are also available. 

 h2. Pre-Foreman 1.1 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, perl, 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/environments?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|   
 |_.Architectures | 
 |/architectures|POST|Create a new Architecture|{architecture : {"name":string}}| 
 |/architectures/NAME|DELETE|Delete a Architecture|| 
 |/architectures|GET|Retrieve a list of Architectures|| 
 |/architectures/NAME|PUT|Update an existing Architecture|{architecture : {"name":string}}| 
 |_.Auth source ldaps | 
 |/auth_source_ldaps|POST|Create a new Auth source ldap|{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}}| 
 |/auth_source_ldaps/ID|DELETE|Delete a Auth source ldap|| 
 |/auth_source_ldaps|GET|Retrieve a list of Auth source ldaps|| 
 |/auth_source_ldaps/ID|PUT|Update an existing Auth source ldap|{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}}| 
 |_.Common parameters | 
 |/common_parameters|POST|Create a new Common parameter|{commonparameter : {"name":string, "reference_id":int, "type":string, "value":string}}| 
 |/common_parameters/ID|DELETE|Delete a Common parameter|| 
 |/common_parameters|GET|Retrieve a list of Common parameters|| 
 |/common_parameters/ID|PUT|Update an existing Common parameter|{commonparameter : {"name":string, "reference_id":int, "type":string, "value":string}}| 
 |_.Config templates | 
 |/config_templates|POST|Create a new Config template|{config_template : {"hostgroup_id":int, "name":string, "snippet":boolean, "template":string, "template_kind_id":int}}| 
 |/config_templates/ID|DELETE|Delete a Config template|| 
 |/config_templates|GET|Retrieve a list of Config templates|| 
 |/config_templates/ID|PUT|Update an existing Config template|{config_template : {"hostgroup_id":int, "name":string, "snippet":boolean, "template":string, "template_kind_id":int}}| 
 |/config_templates/build_pxe_default|GET|Deploy the default pxe template to all smart proxies.|| 
 |_.Domains | 
 |/domains|POST|Create a new Domain|{domain : {"dns_id":int, "fullname":string, "name":string}}| 
 |/domains/NAME|DELETE|Delete a Domain|| 
 |/domains|GET|Retrieve a list of Domains|| 
 |/domains/NAME|PUT|Update an existing Domain|{domain : {"dns_id":int, "fullname":string, "name":string}}| 
 |_.Environments | 
 |/environments|POST|Create a new Environment|{environment : {"name":string}}| 
 |/environments/NAME|DELETE|Delete a Environment|| 
 |/environments|GET|Retrieve a list of Environments|| 
 |/environments/NAME|PUT|Update an existing Environment|{environment : {"name":string}}| 
 |_.Fact names | 
 |/facts|GET| Gets list of all fact names| 
 |/facts/<factname>/values| GET | return all hosts with the given factname and its value| 
 |_.Fact values | 
 |/fact_values|POST|Create a new Fact value|{factvalue : {"fact_name_id":int, "host_id":int, "value":string}}| 
 |/fact_values|GET|Retrieve a list of Fact values|| 
 |_.Hostgroups | 
 |/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/ID|DELETE|Delete a Hostgroup|| 
 |/hostgroups|GET|Retrieve a list of Hostgroups|| 
 |/hostgroups/ID|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}}| 
 |_.Hosts | 
 |/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/FQDN|DELETE|Delete a Host|| 
 |/hosts|GET|Retrieve a list of Hosts|| 
 |/hosts/FQDN|PUT|Update an existing 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/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|Move host to Build state|| |/hosts/FQDN/setBuild|GET|List of disabled hosts(only name)|| 
 |/hosts/FQDN/facts|GET|Returns host facts|| 
 |/hosts/FQDN/puppetclasses|GET|Returns host classes (direct and indirect(via a hostgroup)|| 
 |/hosts/FQDN/reports|GET|Reports for host FQDN || 
 |/hosts/FQDN/reports/last|GET|Last report for host FQDN || 
 |/hosts/FQDN/pxe_config|GET|Returns syslinux configuration file for fqdn|| 
 |_.Hypervisors | 
 |/hypervisors|POST|Create a new Hypervisor|{hypervisor : {"kind":string, "name":string, "uri":string}}| 
 |/hypervisors/ID|DELETE|Delete a Hypervisor|| 
 |/hypervisors|GET|Retrieve a list of Hypervisors|| 
 |/hypervisors/ID|PUT|Update an existing Hypervisor|{hypervisor : {"kind":string, "name":string, "uri":string}}| 
 |_.Smart Variables | 
 |/lookup_keys|POST|Create a new SmartVar key|{lookupkey : {"key":string}}| 
 |/lookup_keys/ID|DELETE|Delete a Smart key|| 
 |/lookup_keys|GET|Retrieve a list of Smartvar keys|| 
 |/lookup_keys/ID|PUT|Update an existing Smart key|{lookupkey : {"key":string}}| 
 |_.Smart Variables values | 
 |/lookup_values|POST|Create a new SmartVar value|{lookupvalue : {"lookup_key_id":integer, "match":string, "value":string}}| 
 |/lookup_values/ID|DELETE|Delete a Smart value|| 
 |/lookup_values|GET|Retrieve a list of Smartvar values|| 
 |/lookup_values/ID|PUT|Update an existing Smart value|{lookupvalue : {"value":string}}| 
 |_.Medias | 
 |/media|POST|Create a new Medium|{medium : {"name":string, "path":string}}| 
 |/media/ID|DELETE|Delete a Medium|| 
 |/media|GET|Retrieve a list of Media|| 
 |/media/ID|PUT|Update an existing Medium|{medium : {"name":string, "path":string}}| 
 |_.Models | 
 |/models|POST|Create a new Model|{model : {"info":string, "name":string}}| 
 |/models/ID|DELETE|Delete a Model|| 
 |/models|GET|Retrieve a list of Models|| 
 |/models/ID|PUT|Update an existing Model|{model : {"info":string, "name":string}}| 
 |_.Operatingsystems | 
 |/operatingsystems|POST|Create a new Operatingsystem|{operatingsystem : {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}| 
 |/operatingsystems/ID|DELETE|Delete a Operatingsystem|| 
 |/operatingsystems|GET|Retrieve a list of Operatingsystems|| 
 |/operatingsystems/ID|PUT|Update an existing Operatingsystem|{operatingsystem : {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}| 
 |/operatingsystems/ID/bootfiles?media=<media_name>&architecture=x86_64|GET|tftp boot files and their respective urls (where they can be found)|| 
 |_.Ptables | 
 |/ptables|POST|Create a new Ptable|{ptable : {"layout":string, "name":string, "operatingsystem_id":int}}| 
 |/ptables/ID|DELETE|Delete a Ptable|| 
 |/ptables|GET|Retrieve a list of Ptables|| 
 |/ptables/ID|PUT|Update an existing Ptable|{ptable : {"layout":string, "name":string, "operatingsystem_id":int}}| 
 |_.Puppetclasses | 
 |/puppetclasses|POST|Create a new Puppetclass|{puppetclass : {"name":string, "nameindicator":string, "operatingsystem_id":int}}| 
 |/puppetclasses/ID|DELETE|Delete a Puppetclass|| 
 |/puppetclasses|GET|Retrieve a list of Puppetclasses|| 
 |/puppetclasses/ID|PUT|Update an existing Puppetclass|{puppetclass : {"name":string, "nameindicator":string, "operatingsystem_id":int}}| 
 |_.Reports | 
 |/reports|POST|Create a new Report|{report : {"host_id":int, "metrics":string, "reported_at":string, "status":string}}| 
 |/reports/ID|DELETE|Delete a Report|| 
 |/reports/last|GET|Retrieve the last report information|| 
 |/reports?numreports=xx|GET|Retrieve reports xx items at a single time|| 
 |_.Roles | 
 |/roles|POST|Create a new Role|{role : {"builtin":string, "name":string, "permissions":string}}| 
 |/roles/ID|DELETE|Delete a Role|| 
 |/roles|GET|Retrieve a list of Roles|| 
 |/roles/ID|PUT|Update an existing Role|{role : {"builtin":string, "name":string, "permissions":string}}| 
 |_.Smart proxies | 
 |/smart_proxies|POST|Create a new Smart proxy|{smartproxy : {"name":string, "url":string}}| 
 |/smart_proxies/ID|DELETE|Delete a Smart proxy|| 
 |/smart_proxies|GET|Retrieve a list of Smart proxies|| 
 |/smart_proxies/ID|PUT|Update an existing Smart proxy|{smartproxy : {"name":string, "url":string}}| 
 |_.Subnets | 
 |/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/ID|DELETE|Delete a Subnet|| 
 |/subnets|GET|Retrieve a list of Subnets|| 
 |/subnets/ID|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}}| 
 |_.Usergroups | 
 |/usergroups|POST|Create a new Usergroup|{usergroup : {"name":string}}| 
 |/usergroups/ID|DELETE|Delete a Usergroup|| 
 |/usergroups|GET|Retrieve a list of Usergroups|| 
 |/usergroups/ID|PUT|Update an existing Usergroup|{usergroup : {"name":string}}| 
 |_.Users | 
 |/users|POST|Create a 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}}| 
 |/users/ID|DELETE|Delete a User|| 
 |/users|GET|Retrieve a list of Users|| 
 |/users/ID|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}}| 
 |_.Miscellaneous | 
 |/dashboard|GET|Summary statistcs (total hosts, active hosts, hosts in error etc)|| 
 |/status|GET|System status (result ok/failed, database lag in miliseconds)|| 




 see also [[Smart-Proxy:API]] 

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

 h2. New version of API 

 There is a new version of API being developed. Version 1 will cover current API.  

 * Source code lives in source:app/controllers/api 
 * Documentation can be accessed on http://path.to.foreman/apidoc 
 * [[API OAuth]]