Project

General

Profile

API » History » Version 13

Justin Sherrill, 02/21/2011 01:39 PM

1 1 Ohad Levy
h1. API
2
3 8 Ohad Levy
*NOTE*: Version of 0.1-6 or git develop branch are required to use the API
4
5 1 Ohad Levy
Foreman provides a "REST":http://en.wikipedia.org/wiki/Representational_State_Transfer API, communicating via JSON.
6
7 9 Ohad Levy
Please refer to this document for latest information about Foreman API.
8 1 Ohad Levy
9
Examples below are either via curl or ruby rest_client
10
11
most pages can be browsed via adding the format option to the url (at least for get requests), i.e.
12
13
<pre>
14
http://foreman/environemnts?format=json
15
</pre>
16
17
Or using HTTP Headers
18
<pre>
19
curl -H "Content-Type:application/json" -H "Accept:application/json"  http://foreman/hosts
20
</pre>
21
22
Output is JSON formatted, in the last example expect a similar output:
23
24
<pre>
25 10 Ohad Levy
[{"host":{"name":"pm1.local.net"}},{"host":{"name":"pm2.local.net"}}....]
26 1 Ohad Levy
</pre>
27
28 3 Ohad Levy
h2. List of API's
29 1 Ohad Levy
30 12 Justin Sherrill
|_.Path|_.REST Type|_.Description|_.Example Input JSON|  
31 13 Justin Sherrill
|_.Architecture |
32
|/architectures|POST|Create a new Architecture|{architecture : {"name":string}}|
33
|/architectures/false|DELETE|Delete a Architecture|{architecture : {"name":string}}|
34
|/architectures|GET|Retrieve a list of Architectures|
35
|/architectures/false|PUT|Update an existing Architecture|{architecture : {"name":string}}|
36
|_.AuthSourceLdap |
37 12 Justin Sherrill
|/authsourceldaps|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}}|
38 13 Justin Sherrill
|/authsourceldaps/false|DELETE|Delete a Auth source ldap|{authsourceldap : {"name":string}}|
39 11 Justin Sherrill
|/authsourceldaps|GET|Retrieve a list of Auth source ldaps|
40 1 Ohad Levy
|/authsourceldaps/false|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}}|
41 13 Justin Sherrill
|_.CommonParameter |
42
|/commonparameters|POST|Create a new Common parameter|{commonparameter : {"name":string, "reference_id":int, "type":string, "value":string}}|
43
|/commonparameters/false|DELETE|Delete a Common parameter|{commonparameter : {"name":string}}|
44
|/commonparameters|GET|Retrieve a list of Common parameters|
45
|/commonparameters/false|PUT|Update an existing Common parameter|{commonparameter : {"name":string, "reference_id":int, "type":string, "value":string}}|
46
|_.ConfigTemplate |
47
|/configtemplates|POST|Create a new Config template|{configtemplate : {"hostgroup_id":int, "name":string, "snippet":string, "template":string, "template_kind_id":int}}|
48
|/configtemplates/false|DELETE|Delete a Config template|{configtemplate : {"name":string}}|
49
|/configtemplates|GET|Retrieve a list of Config templates|
50
|/configtemplates/false|PUT|Update an existing Config template|{configtemplate : {"hostgroup_id":int, "name":string, "snippet":string, "template":string, "template_kind_id":int}}|
51
|_.Domain |
52 1 Ohad Levy
|/domains|POST|Create a new Domain|{domain : {"dns_id":int, "fullname":string, "name":string}}|
53 13 Justin Sherrill
|/domains/false|DELETE|Delete a Domain|{domain : {"name":string}}|
54 1 Ohad Levy
|/domains|GET|Retrieve a list of Domains|
55
|/domains/false|PUT|Update an existing Domain|{domain : {"dns_id":int, "fullname":string, "name":string}}|
56 13 Justin Sherrill
|_.Environment |
57
|/environments|POST|Create a new Environment|{environment : {"name":string}}|
58
|/environments/false|DELETE|Delete a Environment|{environment : {"name":string}}|
59
|/environments|GET|Retrieve a list of Environments|
60
|/environments/false|PUT|Update an existing Environment|{environment : {"name":string}}|
61
|_.FactValue |
62
|/factvalues|POST|Create a new Fact value|{factvalue : {"fact_name_id":int, "host_id":int, "value":string}}|
63
|/factvalues|GET|Retrieve a list of Fact values|
64
|_.Hostgroup |
65
|/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}}|
66
|/hostgroups/false|DELETE|Delete a Hostgroup|{hostgroup : {"name":string}}|
67
|/hostgroups|GET|Retrieve a list of Hostgroups|
68
|/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}}|
69
|_.Host |
70
|/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}}|
71
|/hosts/false|DELETE|Delete a Host|{host : {"name":string}}|
72
|/hosts|GET|Retrieve a list of Hosts|
73
|/hosts/false|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}}|
74
|_.Hypervisor |
75 1 Ohad Levy
|/hypervisors|POST|Create a new Hypervisor|{hypervisor : {"kind":string, "name":string, "uri":string}}|
76 13 Justin Sherrill
|/hypervisors/false|DELETE|Delete a Hypervisor|{hypervisor : {"name":string}}|
77 1 Ohad Levy
|/hypervisors|GET|Retrieve a list of Hypervisors|
78
|/hypervisors/false|PUT|Update an existing Hypervisor|{hypervisor : {"kind":string, "name":string, "uri":string}}|
79 13 Justin Sherrill
|_.LookupKey |
80
|/lookupkeys|POST|Create a new Lookup key|{lookupkey : {"key":string}}|
81
|/lookupkeys/false|DELETE|Delete a Lookup key|{lookupkey : {}}|
82
|/lookupkeys|GET|Retrieve a list of Lookup keys|
83
|/lookupkeys/false|PUT|Update an existing Lookup key|{lookupkey : {"key":string}}|
84
|_.Medium |
85
|/media|POST|Create a new Medium|{medium : {"name":string, "path":string}}|
86
|/media/false|DELETE|Delete a Medium|{medium : {"name":string}}|
87
|/media|GET|Retrieve a list of Media|
88
|/media/false|PUT|Update an existing Medium|{medium : {"name":string, "path":string}}|
89
|_.Model |
90 11 Justin Sherrill
|/models|POST|Create a new Model|{model : {"info":string, "name":string}}|
91 13 Justin Sherrill
|/models/false|DELETE|Delete a Model|{model : {"name":string}}|
92 12 Justin Sherrill
|/models|GET|Retrieve a list of Models|
93
|/models/false|PUT|Update an existing Model|{model : {"info":string, "name":string}}|
94 13 Justin Sherrill
|_.Operatingsystem |
95
|/operatingsystems|POST|Create a new Operatingsystem|{operatingsystem : {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}|
96
|/operatingsystems/false|DELETE|Delete a Operatingsystem|{operatingsystem : {"name":string}}|
97
|/operatingsystems|GET|Retrieve a list of Operatingsystems|
98
|/operatingsystems/false|PUT|Update an existing Operatingsystem|{operatingsystem : {"major":string, "minor":string, "name":string, "nameindicator":string, "release_name":string, "type":string}}|
99
|_.Ptable |
100
|/ptables|POST|Create a new Ptable|{ptable : {"layout":string, "name":string, "operatingsystem_id":int}}|
101
|/ptables/false|DELETE|Delete a Ptable|{ptable : {"name":string}}|
102
|/ptables|GET|Retrieve a list of Ptables|
103
|/ptables/false|PUT|Update an existing Ptable|{ptable : {"layout":string, "name":string, "operatingsystem_id":int}}|
104
|_.Puppetclass |
105
|/puppetclasses|POST|Create a new Puppetclass|{puppetclass : {"name":string, "nameindicator":string, "operatingsystem_id":int}}|
106
|/puppetclasses/false|DELETE|Delete a Puppetclass|{puppetclass : {"name":string}}|
107
|/puppetclasses|GET|Retrieve a list of Puppetclasses|
108
|/puppetclasses/false|PUT|Update an existing Puppetclass|{puppetclass : {"name":string, "nameindicator":string, "operatingsystem_id":int}}|
109
|_.Report |
110
|/reports|POST|Create a new Report|{report : {"host_id":int, "metrics":string, "reported_at":string, "status":string}}|
111
|/reports/false|DELETE|Delete a Report|{report : {}}|
112
|/reports|GET|Retrieve a list of Reports|
113
|_.Role |
114
|/roles|POST|Create a new Role|{role : {"builtin":string, "name":string, "permissions":string}}|
115
|/roles/false|DELETE|Delete a Role|{role : {"name":string}}|
116
|/roles|GET|Retrieve a list of Roles|
117
|/roles/false|PUT|Update an existing Role|{role : {"builtin":string, "name":string, "permissions":string}}|
118
|_.SmartProxy |
119
|/smartproxies|POST|Create a new Smart proxy|{smartproxy : {"name":string, "url":string}}|
120
|/smartproxies/false|DELETE|Delete a Smart proxy|{smartproxy : {"name":string}}|
121
|/smartproxies|GET|Retrieve a list of Smart proxies|
122
|/smartproxies/false|PUT|Update an existing Smart proxy|{smartproxy : {"name":string, "url":string}}|
123
|_.Subnet |
124
|/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}}|
125
|/subnets/false|DELETE|Delete a Subnet|{subnet : {"name":string}}|
126
|/subnets|GET|Retrieve a list of Subnets|
127
|/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}}|
128
|_.Usergroup |
129 12 Justin Sherrill
|/usergroups|POST|Create a new Usergroup|{usergroup : {"name":string}}|
130 13 Justin Sherrill
|/usergroups/false|DELETE|Delete a Usergroup|{usergroup : {"name":string}}|
131 12 Justin Sherrill
|/usergroups|GET|Retrieve a list of Usergroups|
132
|/usergroups/false|PUT|Update an existing Usergroup|{usergroup : {"name":string}}|
133 13 Justin Sherrill
|_.User |
134 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}}|
135 13 Justin Sherrill
|/users/false|DELETE|Delete a User|{user : {}}|
136 1 Ohad Levy
|/users|GET|Retrieve a list of Users|
137
|/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}}|
138 13 Justin Sherrill
139 1 Ohad Levy
140 4 Ohad Levy
141
142
143
144 1 Ohad Levy
145 12 Justin Sherrill
146
147 1 Ohad Levy
148
149 6 Ohad Levy
150 1 Ohad Levy
|/dashboard|GET|Summary statistcs (total hosts, active hosts, hosts in error etc)|
151
|/fact_values|GET|List of known Facts (value, name and host)|
152
|/hosts/errors|GET|List of hosts in error state(only name)|
153
|/hosts/active|GET|List of active hosts(only name)|
154 7 Ohad Levy
|/hosts/out_of_sync|GET|List of out of sync hosts(only name)|
155 1 Ohad Levy
|/hosts/disabled|GET|List of disabled hosts(only name)|
156
|/hosts/fqdn/setBuild|GET| Enable Host for (re-)build |
157
|/hosts/fqdn/facts|GET| Returns host facts|
158 3 Ohad Levy
|/hosts/fqdn/pxe_config|GET| Returns syslinux configuration file for fqdn|
159
|/operatingsystems/1/bootfiles?media=<media_name>&architecture=x86_64|GET| tftp boot files and their respective urls (where they can be found)|
160
|/puppetclasses|GET|a hash of known Puppetclasses orginazined by module name (module => {:class1, :class2})|
161
162 1 Ohad Levy
163
164
Please raise a new issue if you need additional API's