This repository has been archived by the owner on Aug 3, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 6
/
changeserver-api.html
431 lines (343 loc) · 17.9 KB
/
changeserver-api.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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
<!doctype html>
<html>
<head>
<title>changeserver</title>
<style type="text/css">
body {
font-family: Trebuchet MS, sans-serif;
font-size: 15px;
color: #444;
margin-right: 24px;
}
h1 {
font-size: 25px;
}
h2 {
font-size: 20px;
}
h3 {
font-size: 16px;
font-weight: bold;
}
hr {
height: 1px;
border: 0;
color: #ddd;
background-color: #ddd;
}
.app-desc {
clear: both;
margin-left: 20px;
}
.param-name {
width: 100%;
}
.license-info {
margin-left: 20px;
}
.license-url {
margin-left: 20px;
}
.model {
margin: 0 0 0px 20px;
}
.method {
margin-left: 20px;
}
.method-notes {
margin: 10px 0 20px 0;
font-size: 90%;
color: #555;
}
pre {
padding: 10px;
margin-bottom: 2px;
}
.http-method {
text-transform: uppercase;
}
pre.get {
background-color: #0f6ab4;
}
pre.post {
background-color: #10a54a;
}
pre.put {
background-color: #c5862b;
}
pre.delete {
background-color: #a41e22;
}
.huge {
color: #fff;
}
pre.example {
background-color: #f3f3f3;
padding: 10px;
border: 1px solid #ddd;
}
code {
white-space: pre;
}
.nickname {
font-weight: bold;
}
.method-path {
font-size: 1.5em;
background-color: #0f6ab4;
}
.up {
float:right;
}
.parameter {
width: 500px;
}
.param {
width: 500px;
padding: 10px 0 0 20px;
font-weight: bold;
}
.param-desc {
width: 700px;
padding: 0 0 0 20px;
color: #777;
}
.param-type {
font-style: italic;
}
.param-enum-header {
width: 700px;
padding: 0 0 0 60px;
color: #777;
font-weight: bold;
}
.param-enum {
width: 700px;
padding: 0 0 0 80px;
color: #777;
font-style: italic;
}
.field-label {
padding: 0;
margin: 0;
clear: both;
}
.field-items {
padding: 0 0 15px 0;
margin-bottom: 15px;
}
.return-type {
clear: both;
padding-bottom: 10px;
}
.param-header {
font-weight: bold;
}
.method-tags {
text-align: right;
}
.method-tag {
background: none repeat scroll 0% 0% #24A600;
border-radius: 3px;
padding: 2px 10px;
margin: 2px;
color: #FFF;
display: inline-block;
text-decoration: none;
}
</style>
</head>
<body>
<h1>changeserver</h1>
<div class="app-desc">Changeserver consumes changes from a Postgres replication scheme created by the "transicator_output" plugin and makes them available to consumers via an API. The API supports long polling so that a large number of consumers may be notified of changes.</div>
<div class="app-desc">More information: <a href="http://www.apigee.com/">http://www.apigee.com/</a></div>
<div class="app-desc">Contact Info: <a href="sales@apigee.com">sales@apigee.com</a></div>
<div class="app-desc">Version: 0.0.1</div>
<div class="license-info">Apache 2.0</div>
<div class="license-url">https://www.apache.org/licenses/LICENSE-2.0</div>
<h2>Access</h2>
<h2><a name="__Methods">Methods</a></h2>
[ Jump to <a href="#__Models">Models</a> ]
<h3>Table of Contents </h3>
<div class="method-summary"></div>
<h4><a href="#Default">Default</a></h4>
<ul>
<li><a href="#changesGet"><code><span class="http-method">get</span> /changes</code></a></li>
<li><a href="#healthGet"><code><span class="http-method">get</span> /health</code></a></li>
<li><a href="#markdownGet"><code><span class="http-method">get</span> /markdown</code></a></li>
<li><a href="#readyGet"><code><span class="http-method">get</span> /ready</code></a></li>
</ul>
<h1><a name="Default">Default</a></h1>
<div class="method"><a name="changesGet"/>
<div class="method-path">
<a class="up" href="#__Methods">Up</a>
<pre class="get"><code class="huge"><span class="http-method">get</span> /changes</code></pre></div>
<div class="method-summary"> (<span class="nickname">changesGet</span>)</div>
<div class="method-notes">Retrieve a list of changes. The query parameters may be used to restrict the number of changes that are retrieved or return only changes since a particular sequence. In addition, it is possible to block (aka "long poll") until a new matching change is available. The result will be produced in JSON format unless the Accept header is used to select the protobuf format.</div>
<h3 class="field-label">Query parameters</h3>
<div class="field-items">
<div class="param">scope (required)</div>
<div class="param-desc"><span class="param-type">Query Parameter</span> — The scope limits the changes that are returned. It is extracted from a database column whenever a change is made. Every call to this API must contain at least one scope. Multiple "scope" parameters may also be used. if more than one "scope" is included, then the operation is treated as an "OR" of all the scopes, and the results are sorted by sequence regardless of scope. </div><div class="param">snapshot (optional)</div>
<div class="param-desc"><span class="param-type">Query Parameter</span> — If specified, then this must be set to a "snapshot ID" from Postgres. This will be in the format "xmin:xmax:xip1,xip2,...xipN" and is normally returned by executing "select txid_current_snapshot()". By including this parameter, the change list will never include any data that would be *visible* in the specified snapshot. So in other words, if the value of this parameter comes from a Postgres query executed during a transaction, then the change server will not return any database changes that were already in the snapshot. </div><div class="param">since (optional)</div>
<div class="param-desc"><span class="param-type">Query Parameter</span> — The value of "sequence" from a previous invocation of this API. If so specified, this API will only return changes that happened after the change with the specified sequence. Otherwise, this API will return changes since the beginning. If this parameter is specified, but the specified sequence no longer exists in the database, then a 400 error and the error code "SNAPSHOT_TOO_OLD" will be returned. </div><div class="param">limit (optional)</div>
<div class="param-desc"><span class="param-type">Query Parameter</span> — Limit the number of changes returned by a single API call. The default limit is 100. </div><div class="param">block (optional)</div>
<div class="param-desc"><span class="param-type">Query Parameter</span> — If specified, this sets the number of seconds that the API call will block if there are no changes available since the "since" value for the set of specified scopes. In the event that there are no changes available when the API call is made, the API will block for the specified number of seconds until a matching change appears. If no changes appear in the specified number of seconds, then an empty change list will be returned. </div>
</div> <!-- field-items -->
<h3 class="field-label">Return type</h3>
<div class="return-type">
<a href="#ChangeList">ChangeList</a>
</div>
<!--Todo: process Response Object and its headers, schema, examples -->
<h3 class="field-label">Example data</h3>
<div class="example-data-content-type">Content-Type: application/json</div>
<pre class="example"><code>{
"firstSequence" : "aeiou",
"lastSequence" : "aeiou",
"changes" : [ {
"sequence" : "aeiou",
"newRow" : "{}",
"txid" : 123456789,
"oldRow" : "{}",
"changeSequence" : 123456789,
"commitSequence" : 123456789,
"operation" : "",
"table" : "aeiou",
"commitIndex" : 123456789
} ]
}</code></pre>
<h3 class="field-label">Produces</h3>
This API call produces the following media types according to the <span class="header">Accept</span> request header;
the media type will be conveyed by the <span class="heaader">Content-Type</span> response header.
<ul>
<li><code>application/json</code></li>
<li><code>application/transicator+protobuf</code></li>
</ul>
<h3 class="field-label">Responses</h3>
<h4 class="field-label">200</h4>
Successful response
<a href="#ChangeList">ChangeList</a>
<h4 class="field-label">400</h4>
Invalid input. Error "code" will tell why. a code of "SNAPSHOT_TOO_OLD" means that records dating back to the "since" parameter are not available.
<a href="#Error">Error</a>
</div> <!-- method -->
<hr/>
<div class="method"><a name="healthGet"/>
<div class="method-path">
<a class="up" href="#__Methods">Up</a>
<pre class="get"><code class="huge"><span class="http-method">get</span> /health</code></pre></div>
<div class="method-summary"> (<span class="nickname">healthGet</span>)</div>
<div class="method-notes">Describes whether the server is "healthy." When the server is not healthy, it is not able to process any requests, and should be killed and restarted. If the server was started with a management port enabled, this URL only resolves on that port.</div>
<!--Todo: process Response Object and its headers, schema, examples -->
<h3 class="field-label">Produces</h3>
This API call produces the following media types according to the <span class="header">Accept</span> request header;
the media type will be conveyed by the <span class="heaader">Content-Type</span> response header.
<ul>
<li><code>text/plain</code></li>
<li><code>application/json</code></li>
</ul>
<h3 class="field-label">Responses</h3>
<h4 class="field-label">200</h4>
Everything is fine. No output produced.
<a href="#"></a>
<h4 class="field-label">503</h4>
Server is not healthy. Normally returns the status in textual form, but if JSON is selected in the Accept header than JSON will be returned.
<a href="#Status">Status</a>
</div> <!-- method -->
<hr/>
<div class="method"><a name="markdownGet"/>
<div class="method-path">
<a class="up" href="#__Methods">Up</a>
<pre class="get"><code class="huge"><span class="http-method">get</span> /markdown</code></pre></div>
<div class="method-summary"> (<span class="nickname">markdownGet</span>)</div>
<div class="method-notes">Changes the state of the server to denote that it has been marked down. After this is called, the "/ready" path will return 503, and all other API calls except "/health" will also fail with 503. After this API call has been made, the server will delete its Postgres replication slot when it exits. Management software should call this URL before a planned shutdown to ensure cleanup of Postgres resources. If the server was started with a management port enabled, this URL only resolves on that port.</div>
<!--Todo: process Response Object and its headers, schema, examples -->
<h3 class="field-label">Responses</h3>
<h4 class="field-label">200</h4>
Server is now marked down
<a href="#"></a>
</div> <!-- method -->
<hr/>
<div class="method"><a name="readyGet"/>
<div class="method-path">
<a class="up" href="#__Methods">Up</a>
<pre class="get"><code class="huge"><span class="http-method">get</span> /ready</code></pre></div>
<div class="method-summary"> (<span class="nickname">readyGet</span>)</div>
<div class="method-notes">Describes whether the server is "ready." When the server is not ready, it is not able to process any requests. Load balancers should not route calls to a server that is not ready. The server may not be ready because it is still starting up, or because it is shutting down. It is possible for a server to be "ready" but still "healthy." If the server was started with a management port enabled, this URL only resolves on that port.</div>
<!--Todo: process Response Object and its headers, schema, examples -->
<h3 class="field-label">Produces</h3>
This API call produces the following media types according to the <span class="header">Accept</span> request header;
the media type will be conveyed by the <span class="heaader">Content-Type</span> response header.
<ul>
<li><code>text/plain</code></li>
<li><code>application/json</code></li>
</ul>
<h3 class="field-label">Responses</h3>
<h4 class="field-label">200</h4>
Everything is fine. No output produced.
<a href="#"></a>
<h4 class="field-label">503</h4>
Server is not ready. Normally returns the status in textual form, but if JSON is selected in the Accept header than JSON will be returned.
<a href="#Status">Status</a>
</div> <!-- method -->
<hr/>
<div class="up"><a href="#__Models">Up</a></div>
<h2><a name="__Models">Models</a></h2>
[ Jump to <a href="#__Methods">Methods</a> ]
<h3>Table of Contents</h3>
<ol>
<li><a href="#Change"><code>Change</code></a></li>
<li><a href="#ChangeList"><code>ChangeList</code></a></li>
<li><a href="#Error"><code>Error</code></a></li>
<li><a href="#Status"><code>Status</code></a></li>
<li><a href="#Value"><code>Value</code></a></li>
</ol>
<div class="model">
<h3 class="field-label"><a name="Change">Change - </a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'>A single change.</div>
<div class="field-items">
<div class="param">operation (optional)</div><div class="param-desc"><span class="param-type"><a href="#integer">Integer</a></span> The type of change. "1" denotes an insert. "2" denotes an update. "3" denotes a delete. </div>
<div class="param">table (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The name of the database table that was changed. </div>
<div class="param">sequence (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The unique, ordered identifier of the change in the list of changes. </div>
<div class="param">commitSequence (optional)</div><div class="param-desc"><span class="param-type"><a href="#long">Long</a></span> The order of this transaction's commit in the list of changes. format: int64</div>
<div class="param">changeSequence (optional)</div><div class="param-desc"><span class="param-type"><a href="#long">Long</a></span> The order of this change in the list of changes. Since transactions commit in different orders, changes are not necessarily shown in this order format: int64</div>
<div class="param">commitIndex (optional)</div><div class="param-desc"><span class="param-type"><a href="#long">Long</a></span> The order of this change in the list of changes for a particular transaction. When multiple changes are made in a transaction, they have the same commitSequence but different values of commitIndex. format: int64</div>
<div class="param">txid (optional)</div><div class="param-desc"><span class="param-type"><a href="#long">Long</a></span> The database transaction ID for this change format: int64</div>
<div class="param">newRow (optional)</div><div class="param-desc"><span class="param-type"><a href="#object">Object</a></span> The new value of the row for an insert or update operation. The fields in the object are named after the fields in the row, and each field's value is a "Value" object. </div>
<div class="param">oldRow (optional)</div><div class="param-desc"><span class="param-type"><a href="#object">Object</a></span> The old value of the row for a delete or update operation. </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3 class="field-label"><a name="ChangeList">ChangeList - </a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'>A set of changes.</div>
<div class="field-items">
<div class="param">firstSequence (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The oldest sequence present in the databse </div>
<div class="param">lastSequence (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The newest sequence present in the databse </div>
<div class="param">changes (optional)</div><div class="param-desc"><span class="param-type"><a href="#Change">array[Change]</a></span> A list of changes, in sequence order. </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3 class="field-label"><a name="Error">Error - </a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'>An error in processing by the server.</div>
<div class="field-items">
<div class="param">code </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> A short symbolic description of the error </div>
<div class="param">error </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> A short description of the error </div>
<div class="param">description (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> A longer description of the error </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3 class="field-label"><a name="Status">Status - </a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'>A response sent by a server that has been marked down.</div>
<div class="field-items">
<div class="param">reason </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The reason that a server has been marked down. Suitable for writing in to logs and diagnostic errors. </div>
</div> <!-- field-items -->
</div>
<div class="model">
<h3 class="field-label"><a name="Value">Value - </a> <a class="up" href="#__Models">Up</a></h3>
<div class='model-description'>The value of a row in the "newRow" or "oldRow" property of a change.</div>
<div class="field-items">
<div class="param">value </div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The row value in string form </div>
<div class="param">type </div><div class="param-desc"><span class="param-type"><a href="#integer">Integer</a></span> The Postgres numeric type of the field </div>
</div> <!-- field-items -->
</div>
</body>
</html>