Project

General

Profile

API » History » Version 43

Dominic Cleal, 07/01/2013 06:24 AM
formatting

1 1 Ohad Levy
h1. API
2
3 41 Dominic Cleal
h2. Foreman 1.1 API
4 1 Ohad Levy
5 41 Dominic Cleal
The documentation previously held on this page has been incorporated into the main "theforeman.org":http://theforeman.org/ web site.  You can access it here:
6 1 Ohad Levy
7 41 Dominic Cleal
* "*Foreman API documentation*":http://theforeman.org/api.html
8 1 Ohad Levy
9 41 Dominic Cleal
*NOTE*: Starting with Foreman 1.1 API documentation can be auto generated on your installation using @rake apipie:static@, then access using /apidoc on your foreman instance. Auto generated Ruby binding and CLI are also available.
10
11 42 Dominic Cleal
h2. DEPRECATED: pre-Foreman 1.1 API
12
13 43 Dominic Cleal
*This API is officially deprecated as of Foreman 1.2.  Please use the API under /api instead, see the "Foreman API documentation":http://theforeman.org/api.html for full details.*
14 41 Dominic Cleal
15
*NOTE*: Version of 0.1-6 or git develop branch are required to use the API
16
17 1 Ohad Levy
Foreman provides a "REST":http://en.wikipedia.org/wiki/Representational_State_Transfer API, communicating via JSON.
18
19 9 Ohad Levy
Please refer to this document for latest information about Foreman API.
20 1 Ohad Levy
21 33 Jan van Eldik
[[Examples]] below are either via curl, perl, ruby rest_client
22 32 Florian Koch
23 1 Ohad Levy
24
most pages can be browsed via adding the format option to the url (at least for get requests), i.e.
25
26
<pre>
27 25 Romain Vrignaud
http://foreman/environments?format=json
28 1 Ohad Levy
</pre>
29
30
Or using HTTP Headers
31
<pre>
32
curl -H "Content-Type:application/json" -H "Accept:application/json"  http://foreman/hosts
33
</pre>
34
35
Output is JSON formatted, in the last example expect a similar output:
36
37
<pre>
38 10 Ohad Levy
[{"host":{"name":"pm1.local.net"}},{"host":{"name":"pm2.local.net"}}....]
39 1 Ohad Levy
</pre>
40
41 3 Ohad Levy
h2. List of API's
42 1 Ohad Levy
43 12 Justin Sherrill
|_.Path|_.REST Type|_.Description|_.Example Input JSON|  
44 14 Justin Sherrill
|_.Architectures |
45 13 Justin Sherrill
|/architectures|POST|Create a new Architecture|{architecture : {"name":string}}|
46 26 Romain Vrignaud
|/architectures/NAME|DELETE|Delete a Architecture||
47 18 Justin Sherrill
|/architectures|GET|Retrieve a list of Architectures||
48 26 Romain Vrignaud
|/architectures/NAME|PUT|Update an existing Architecture|{architecture : {"name":string}}|
49 16 Justin Sherrill
|_.Auth source ldaps |
50 15 Justin Sherrill
|/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}}|
51 18 Justin Sherrill
|/auth_source_ldaps/ID|DELETE|Delete a Auth source ldap||
52
|/auth_source_ldaps|GET|Retrieve a list of Auth source ldaps||
53 15 Justin Sherrill
|/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}}|
54 16 Justin Sherrill
|_.Common parameters |
55 15 Justin Sherrill
|/common_parameters|POST|Create a new Common parameter|{commonparameter : {"name":string, "reference_id":int, "type":string, "value":string}}|
56 18 Justin Sherrill
|/common_parameters/ID|DELETE|Delete a Common parameter||
57
|/common_parameters|GET|Retrieve a list of Common parameters||
58 15 Justin Sherrill
|/common_parameters/ID|PUT|Update an existing Common parameter|{commonparameter : {"name":string, "reference_id":int, "type":string, "value":string}}|
59 16 Justin Sherrill
|_.Config templates |
60 34 Pedro Gomes
|/config_templates|POST|Create a new Config template|{config_template : {"hostgroup_id":int, "name":string, "snippet":boolean, "template":string, "template_kind_id":int}}|
61 18 Justin Sherrill
|/config_templates/ID|DELETE|Delete a Config template||
62
|/config_templates|GET|Retrieve a list of Config templates||
63 34 Pedro Gomes
|/config_templates/ID|PUT|Update an existing Config template|{config_template : {"hostgroup_id":int, "name":string, "snippet":boolean, "template":string, "template_kind_id":int}}|
64 15 Justin Sherrill
|/config_templates/build_pxe_default|GET|Deploy the default pxe template to all smart proxies.||
65 1 Ohad Levy
|_.Domains |
66
|/domains|POST|Create a new Domain|{domain : {"dns_id":int, "fullname":string, "name":string}}|
67 18 Justin Sherrill
|/domains/NAME|DELETE|Delete a Domain||
68
|/domains|GET|Retrieve a list of Domains||
69 15 Justin Sherrill
|/domains/NAME|PUT|Update an existing Domain|{domain : {"dns_id":int, "fullname":string, "name":string}}|
70 1 Ohad Levy
|_.Environments |
71
|/environments|POST|Create a new Environment|{environment : {"name":string}}|
72 18 Justin Sherrill
|/environments/NAME|DELETE|Delete a Environment||
73
|/environments|GET|Retrieve a list of Environments||
74 15 Justin Sherrill
|/environments/NAME|PUT|Update an existing Environment|{environment : {"name":string}}|
75 30 Corey Osman
|_.Fact names |
76 31 Corey Osman
|/facts|GET| Gets list of all fact names|
77 30 Corey Osman
|/facts/<factname>/values| GET | return all hosts with the given factname and its value|
78 16 Justin Sherrill
|_.Fact values |
79 15 Justin Sherrill
|/fact_values|POST|Create a new Fact value|{factvalue : {"fact_name_id":int, "host_id":int, "value":string}}|
80 18 Justin Sherrill
|/fact_values|GET|Retrieve a list of Fact values||
81 14 Justin Sherrill
|_.Hostgroups |
82 1 Ohad Levy
|/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}}|
83 27 Romain Vrignaud
|/hostgroups/ID|DELETE|Delete a Hostgroup||
84 18 Justin Sherrill
|/hostgroups|GET|Retrieve a list of Hostgroups||
85 27 Romain Vrignaud
|/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}}|
86 1 Ohad Levy
|_.Hosts |
87 18 Justin Sherrill
|/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}}|
88
|/hosts/FQDN|DELETE|Delete a Host||
89 15 Justin Sherrill
|/hosts|GET|Retrieve a list of Hosts||
90
|/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}}|
91 1 Ohad Levy
|/hosts/errors|GET|List of hosts in error state(only name)||
92 15 Justin Sherrill
|/hosts/active|GET|List of active hosts (only name)||
93
|/hosts/out_of_sync|GET|List of out of sync hosts(only name)||
94
|/hosts/disabled|GET|List of disabled hosts(only name)||
95 41 Dominic Cleal
|/hosts/FQDN/setBuild|GET|Move host to Build state||
96 15 Justin Sherrill
|/hosts/FQDN/facts|GET|Returns host facts||
97 23 Ohad Levy
|/hosts/FQDN/puppetclasses|GET|Returns host classes (direct and indirect(via a hostgroup)||
98 24 Ohad Levy
|/hosts/FQDN/reports|GET|Reports for host FQDN ||
99
|/hosts/FQDN/reports/last|GET|Last report for host FQDN ||
100 15 Justin Sherrill
|/hosts/FQDN/pxe_config|GET|Returns syslinux configuration file for fqdn||
101 1 Ohad Levy
|_.Hypervisors |
102
|/hypervisors|POST|Create a new Hypervisor|{hypervisor : {"kind":string, "name":string, "uri":string}}|
103 18 Justin Sherrill
|/hypervisors/ID|DELETE|Delete a Hypervisor||
104
|/hypervisors|GET|Retrieve a list of Hypervisors||
105 15 Justin Sherrill
|/hypervisors/ID|PUT|Update an existing Hypervisor|{hypervisor : {"kind":string, "name":string, "uri":string}}|
106 35 Ohad Levy
|_.Smart Variables |
107
|/lookup_keys|POST|Create a new SmartVar key|{lookupkey : {"key":string}}|
108
|/lookup_keys/ID|DELETE|Delete a Smart key||
109
|/lookup_keys|GET|Retrieve a list of Smartvar keys||
110
|/lookup_keys/ID|PUT|Update an existing Smart key|{lookupkey : {"key":string}}|
111 1 Ohad Levy
|_.Smart Variables values |
112 38 Ohad Levy
|/lookup_values|POST|Create a new SmartVar value|{lookupvalue : {"lookup_key_id":integer, "match":string, "value":string}}|
113 35 Ohad Levy
|/lookup_values/ID|DELETE|Delete a Smart value||
114
|/lookup_values|GET|Retrieve a list of Smartvar values||
115
|/lookup_values/ID|PUT|Update an existing Smart value|{lookupvalue : {"value":string}}|
116 16 Justin Sherrill
|_.Medias |
117 1 Ohad Levy
|/media|POST|Create a new Medium|{medium : {"name":string, "path":string}}|
118 18 Justin Sherrill
|/media/ID|DELETE|Delete a Medium||
119
|/media|GET|Retrieve a list of Media||
120 15 Justin Sherrill
|/media/ID|PUT|Update an existing Medium|{medium : {"name":string, "path":string}}|
121 13 Justin Sherrill
|_.Models |
122 12 Justin Sherrill
|/models|POST|Create a new Model|{model : {"info":string, "name":string}}|
123 18 Justin Sherrill
|/models/ID|DELETE|Delete a Model||
124
|/models|GET|Retrieve a list of Models||
125 15 Justin Sherrill
|/models/ID|PUT|Update an existing Model|{model : {"info":string, "name":string}}|
126 13 Justin Sherrill
|_.Operatingsystems |
127
|/operatingsystems|POST|Create a new Operatingsystem|{operatingsystem : {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}|
128 18 Justin Sherrill
|/operatingsystems/ID|DELETE|Delete a Operatingsystem||
129
|/operatingsystems|GET|Retrieve a list of Operatingsystems||
130 1 Ohad Levy
|/operatingsystems/ID|PUT|Update an existing Operatingsystem|{operatingsystem : {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}|
131 20 Ohad Levy
|/operatingsystems/ID/bootfiles?media=<media_name>&architecture=x86_64|GET|tftp boot files and their respective urls (where they can be found)||
132 15 Justin Sherrill
|_.Ptables |
133 13 Justin Sherrill
|/ptables|POST|Create a new Ptable|{ptable : {"layout":string, "name":string, "operatingsystem_id":int}}|
134 18 Justin Sherrill
|/ptables/ID|DELETE|Delete a Ptable||
135
|/ptables|GET|Retrieve a list of Ptables||
136 13 Justin Sherrill
|/ptables/ID|PUT|Update an existing Ptable|{ptable : {"layout":string, "name":string, "operatingsystem_id":int}}|
137 15 Justin Sherrill
|_.Puppetclasses |
138 13 Justin Sherrill
|/puppetclasses|POST|Create a new Puppetclass|{puppetclass : {"name":string, "nameindicator":string, "operatingsystem_id":int}}|
139 18 Justin Sherrill
|/puppetclasses/ID|DELETE|Delete a Puppetclass||
140
|/puppetclasses|GET|Retrieve a list of Puppetclasses||
141 13 Justin Sherrill
|/puppetclasses/ID|PUT|Update an existing Puppetclass|{puppetclass : {"name":string, "nameindicator":string, "operatingsystem_id":int}}|
142 15 Justin Sherrill
|_.Reports |
143 18 Justin Sherrill
|/reports|POST|Create a new Report|{report : {"host_id":int, "metrics":string, "reported_at":string, "status":string}}|
144 1 Ohad Levy
|/reports/ID|DELETE|Delete a Report||
145 24 Ohad Levy
|/reports/last|GET|Retrieve the last report information||
146 28 Corey Osman
|/reports?numreports=xx|GET|Retrieve reports xx items at a single time||
147 13 Justin Sherrill
|_.Roles |
148 1 Ohad Levy
|/roles|POST|Create a new Role|{role : {"builtin":string, "name":string, "permissions":string}}|
149 18 Justin Sherrill
|/roles/ID|DELETE|Delete a Role||
150
|/roles|GET|Retrieve a list of Roles||
151 13 Justin Sherrill
|/roles/ID|PUT|Update an existing Role|{role : {"builtin":string, "name":string, "permissions":string}}|
152 15 Justin Sherrill
|_.Smart proxies |
153 16 Justin Sherrill
|/smart_proxies|POST|Create a new Smart proxy|{smartproxy : {"name":string, "url":string}}|
154 18 Justin Sherrill
|/smart_proxies/ID|DELETE|Delete a Smart proxy||
155
|/smart_proxies|GET|Retrieve a list of Smart proxies||
156 15 Justin Sherrill
|/smart_proxies/ID|PUT|Update an existing Smart proxy|{smartproxy : {"name":string, "url":string}}|
157
|_.Subnets |
158 13 Justin Sherrill
|/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}}|
159 18 Justin Sherrill
|/subnets/ID|DELETE|Delete a Subnet||
160
|/subnets|GET|Retrieve a list of Subnets||
161 13 Justin Sherrill
|/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}}|
162 15 Justin Sherrill
|_.Usergroups |
163 13 Justin Sherrill
|/usergroups|POST|Create a new Usergroup|{usergroup : {"name":string}}|
164 18 Justin Sherrill
|/usergroups/ID|DELETE|Delete a Usergroup||
165
|/usergroups|GET|Retrieve a list of Usergroups||
166 4 Ohad Levy
|/usergroups/ID|PUT|Update an existing Usergroup|{usergroup : {"name":string}}|
167 1 Ohad Levy
|_.Users |
168 12 Justin Sherrill
|/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}}|
169 18 Justin Sherrill
|/users/ID|DELETE|Delete a User||
170
|/users|GET|Retrieve a list of Users||
171 1 Ohad Levy
|/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}}|
172 6 Ohad Levy
|_.Miscellaneous |
173 17 Justin Sherrill
|/dashboard|GET|Summary statistcs (total hosts, active hosts, hosts in error etc)||
174 21 Lukas Zapletal
|/status|GET|System status (result ok/failed, database lag in miliseconds)||
175 18 Justin Sherrill
176 1 Ohad Levy
177
178
179 22 Ohad Levy
see also [[Smart-Proxy:API]]
180 1 Ohad Levy
181
Please raise a new issue if you need additional API's
182 40 Petr Chalupa
183
h2. New version of API
184
185
There is a new version of API being developed. Version 1 will cover current API. 
186
187
* Source code lives in source:app/controllers/api
188
* Documentation can be accessed on http://path.to.foreman/apidoc
189
* [[API OAuth]]