Project

General

Profile

Actions
History

Howtos »

API » History » Revision 11

« Previous | Revision 11/45 (diff) | Next »
Justin Sherrill, 02/21/2011 12:55 PM

API

NOTE: Version of 0.1-6 or git develop branch are required to use the API

Foreman provides a REST 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.

http://foreman/environemnts?format=json

Or using HTTP Headers

curl -H "Content-Type:application/json" -H "Accept:application/json"  http://foreman/hosts

Output is JSON formatted, in the last example expect a similar output:

[{"host":{"name":"pm1.local.net"}},{"host":{"name":"pm2.local.net"}}....]

List of API's

Path REST Type Example JSON
/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

Updated by Justin Sherrill almost 14 years ago · 45 revisions