-
Notifications
You must be signed in to change notification settings - Fork 69
/
Copy pathfile.http_api_index.html
197 lines (141 loc) · 7.15 KB
/
file.http_api_index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>
File: http_api_index
— Documentation by YARD 0.8.7.3
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
<script type="text/javascript" charset="utf-8">
hasFrames = window.top.frames.main ? true : false;
relpath = '';
framesUrl = "frames.html#!" + escape(window.location.href);
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: http_api_index</span>
<div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
Class List
</a>
<a class="full_list_link" id="method_list_link"
href="method_list.html">
Method List
</a>
<a class="full_list_link" id="file_list_link"
href="file_list.html">
File List
</a>
</div>
<div class="clear"></div>
</div>
<iframe id="search_frame"></iframe>
<div id="content"><div id='filecontents'><h2>V1 API Services</h2>
<p>Puppet Agents use various network services which the Puppet Master provides in
order to manage systems. Other systems can access these services in order to
put the information that the Puppet Master has to use.</p>
<p>The V1 API is all based off of dispatching to puppet's internal "indirector"
framework. Every HTTP endpoint in V1 follows the form
<code>/:environment/:indirection/:key</code>, where
* <code>:environment</code> is the name of the environment that should be in effect for
the request. Not all endpoints need an environment, but the path component
must always be specified.
* <code>:indirection</code> is the indirection to dispatch the request to.
* <code>:key</code> is the "key" portion of the indirection call.</p>
<p>Using this API requires a significant amount of understanding of how puppet's
internal services are structured. The following documents provide some
specification for what is available and the ways in which they can be
interacted with.</p>
<h3>Configuration Management Services</h3>
<p>These services are all related to how the Puppet Agent is able to manage the
configuration of a node.</p>
<ul>
<li><a href="file.http_catalog.html" title="Catalog">Catalog</a></li>
<li><a href="file.http_file_bucket_file.html" title="File Bucket File">File Bucket File</a></li>
<li><a href="file.http_file_content.html" title="File Content">File Content</a></li>
<li><a href="file.http_file_metadata.html" title="File Metadata">File Metadata</a></li>
<li><a href="file.http_report.html" title="Report">Report</a></li>
</ul>
<h3>Informational Services</h3>
<p>These services all provide extra information that can be used to understand how
the Puppet Master will be providing configuration management information to
Puppet Agents.</p>
<ul>
<li><a href="file.http_facts.html" title="Facts">Facts</a></li>
<li><a href="file.http_node.html" title="Node">Node</a></li>
<li><a href="file.http_resource_type.html" title="Resource Type">Resource Type</a></li>
<li><a href="file.http_status.html" title="Status">Status</a></li>
</ul>
<h3>SSL Certificate Related Services</h3>
<p>These services are all in support of Puppet's PKI system.</p>
<ul>
<li><a href="file.http_certificate.html" title="Certificate">Certificate</a></li>
<li><a href="file.http_certificate_request.html" title="Certificate Signing Requests">Certificate Signing Requests</a></li>
<li><a href="file.http_certificate_status.html" title="Certificate Status">Certificate Status</a></li>
<li><a href="file.http_certificate_revocation_list.html" title="Certificate Revocation List">Certificate Revocation List</a></li>
</ul>
<h2>V2 HTTP API</h2>
<p>The V2 HTTP API is accessed by prefixing requests with <code>/v2.0</code>. Authorization for
these endpoints is still controlled with the <code>auth.conf</code> authorization system
in puppet. When specifying the authorization of the V2 endpoints in <code>auth.conf</code>
the <code>/v2.0</code> prefix on V2 API paths must be retained; the full request path is used.</p>
<p>The V2 API will only accept payloads formatted as JSON and respond with JSON
(MIME application/json).</p>
<h3>Endpoints</h3>
<ul>
<li><a href="file.http_environments.html" title="Environments">Environments</a></li>
</ul>
<h3>Error Responses</h3>
<p>All V2 API endpoints will respond to error conditions in a uniform manner and
use standard HTTP response code to signify those errors.</p>
<ul>
<li>When the client submits a malformed request, the API will return a 400 Bad
Request response.</li>
<li>When the client is not authorized, the API will return a 403 Not Authorized
response.</li>
<li>When the client attempts to use an HTTP method that is not permissible for
the endpoint, the API will return a 405 Method Not Allowed response.</li>
<li>When the client asks for a response in a format other than JSON, the API will
return a 406 Unacceptable response.</li>
<li>When the server encounters an unexpected error during the handling of a
request, it will return a 500 Server Error response.</li>
<li>When the server is unable to find an endpoint handler for the request that
starts with <code>/v2.0</code>, it will return a 404 Not Found response</li>
</ul>
<p>The V2 API paths are prefixed with <code>/v2.0</code> instead of <code>/v2</code> so that it is able
to respond with 404, but not interfere with any environments in the V1 API.
<code>v2</code> is a valid environment name, but <code>v2.0</code> is not.</p>
<p>All error responses will contain a body, except when it is a HEAD request. The
error responses will uniformly be a JSON object with the following properties:</p>
<ul>
<li><code>message</code>: [String] A human readable message explaining the error.</li>
<li><code>issue_kind</code>: [String] A unique label to identify the error class.</li>
<li><code>stacktrace</code> (only for 5xx errors): [Array<String>] A stacktrace to where the error occurred.</li>
</ul>
<p>A <a href="file.error.html" title="JSON schema for the error objects">JSON schema for the error objects</a> is also available.</p>
<h2>Serialization Formats</h2>
<p>Puppet sends messages using several different serialization formats. Not all
REST services support all of the formats.</p>
<ul>
<li><a href="file.pson.html" title="PSON">PSON</a></li>
<li><a href="http://www.yaml.org/spec/1.2/spec.html" target="_parent" title="YAML">YAML</a></li>
</ul>
</div></div>
<div id="footer">
Generated on Thu Apr 10 18:10:13 2014 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.8.7.3 (ruby-2.0.0).
</div>
</body>
</html>