Skip to content

Commit c7bfd0b

Browse files
zoffixznetzoffixznet
committed
Add page with documentation of public API
1 parent 967b61f commit c7bfd0b

File tree

6 files changed

+224
-72
lines changed

6 files changed

+224
-72
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@
22
/alerts.sqlite.db
33
/static/main.css
44
/static/.sass-cache/
5+
/temp.p6

‎bin/server.p6‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,13 @@ sub MAIN (Str:D :$host = 'localhost', UInt:D :$port = 10000) {
4242
} else { not-found }
4343
}
4444

45+
my subset TemplateContent of Str where * ∈ <
46+
api
47+
>;
48+
get -> TemplateContent $file {
49+
content 'text/html', html-render-template $file
50+
}
51+
4552
my subset StaticContent of Str where * ∈ <
4653
feed-pic.png main.css
4754
rss.svg api.svg twitter.svg camelia.svg
@@ -112,6 +119,15 @@ sub rss-render-alerts(*@alerts) {
112119
~ '</channel></rss>'
113120
}
114121

122+
sub html-render-template($file) {
123+
state %templates;
124+
html-layout-default
125+
%templates{$file} //= 'templates'.IO.add("$file.html").slurp
126+
.subst(:g, '::SITE-HOST::', $SITE-HOST)
127+
.subst: :g, /'::ESCAPE_HTML[::' (.+?) '::]ESCAPE_HTML::'/,
128+
*.[0].Str.&escape-html
129+
}
130+
115131
sub html-render-alerts(*@alerts) {
116132
html-layout-default '<ul id="alerts">'
117133
~ @alerts.map(-> $a {

‎lib/P6lert/Alert.pm6‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
unit class P6lert::Alert;
2-
use HTML::Escape;
32
use Subset::Helper;
43
use DateTime::Format;
54

‎static/main.css‎

Lines changed: 0 additions & 70 deletions
This file was deleted.

‎static/main.scss‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
$color1: #F3F1AF;
33
$color2: #F9420A;
44
$color3: #AECBEB;
5-
$color4: #FFFFFF;
5+
$color4: #FaFaFa;
66
$color5: #2B2B2B;
77

88
$page-bg: lighten($color1, 10%);
@@ -24,15 +24,48 @@ body {
2424
font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
2525
}
2626

27+
p, li, pre {
28+
line-height: 1.7em;
29+
}
30+
2731
#content {
2832
margin: 10px auto;
2933
max-width: 1100px;
3034
}
3135

36+
.container {
37+
background: $color4;
38+
margin: 20px 0;
39+
padding: 10px 40px;
40+
border-radius: $radius;
41+
border: 1px solid $border-color;
42+
}
43+
44+
pre {
45+
padding: 10px;
46+
background: darken($color4, 5%);
47+
border-radius: $radius;
48+
}
3249
code, kbd, pre, samp {
3350
font-family: Menlo, Monaco, Consolas, "Courier New", monospace;
3451
}
3552

53+
a {
54+
color: lighten($text-color, 20%);
55+
text-decoration: underline;
56+
}
57+
a:hover {
58+
text-decoration: none;
59+
}
60+
61+
.back-link {
62+
font-size: 90%;
63+
text-decoration: none;
64+
}
65+
.back-link:hover {
66+
text-decoration: underline;
67+
}
68+
3669
h1 {
3770
font-size: 140%;
3871
letter-spacing: -1px;
@@ -63,6 +96,11 @@ footer, footer * {
6396
color: $muted-text;
6497
}
6598

99+
ul.toc {
100+
margin-left: 1em;
101+
padding-left: 0;
102+
}
103+
66104
#alerts {
67105
list-style-type: none;
68106
padding-left: 0;

‎templates/api.html‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
<a href="/" class="back-link">← back</a>
2+
<div class="container">
3+
4+
<h2 id="toc">Table of Contents</h2>
5+
<ul class="toc">
6+
<li><a href="#api-implementation">API Implementation</a></li>
7+
<li><a href="#api-documentation">API Documentation</a>
8+
<ul>
9+
<li><a href="api-alert-object">Alert Object Structure</a></li>
10+
<li><a href="api-all">All Alerts</a></li>
11+
<li><a href="api-alerts-since">Alerts Since…</a></li>
12+
<li><a href="#api-alert">A Specific Alert</a></li>
13+
</ul>
14+
</li>
15+
</ul>
16+
17+
<h2 id="api-implementation">API Implementations</h2>
18+
19+
<p>Perl 6 implementations of this site's API exist in the form of
20+
<a href="https://modules.perl6.org/repo/WWW::P6lert"><code>WWW::P6lert</code>
21+
module</a> as well as a
22+
<a href="https://modules.perl6.org/repo/p6lert"><code>p6lert</code> command
23+
line utility</a> that lets you view new alerts on your command line.</p>
24+
25+
<h2 id="api-documentation">API Documentation</h2>
26+
27+
<p>This site offers its data via JSON API endpoint. You can use any HTTPS client
28+
and JSON decoder. The examples on this page will use
29+
<a href="https://modules.perl6.org/repo/WWW"><code>WWW</code> module</a>.</p>
30+
31+
<h3 id="api-alert-object">Alert Object Structure</h3>
32+
33+
The JSON object of alerts returned by all endpoints is this:
34+
35+
<pre><code>::ESCAPE_HTML[::{
36+
"id": 3,
37+
"alert": "OMG!!!! STUFF IS ON FIRE!!!",
38+
"severity": "critical",
39+
"affects": "Rakudo 2017.12 and earlier",
40+
"time": 1514320218,
41+
"creator": "Zoffix Znet"
42+
}::]ESCAPE_HTML::</code></pre>
43+
44+
<p>All properties are allways present.</p>
45+
46+
<ul>
47+
<li><code>id</code> - unique ID of the alert - type:
48+
<code>UInt</code></li>
49+
<li><code>alert</code> - full text of the alert - type:
50+
<code>Str</code></li>
51+
<li><code>severity</code> - severity of the alert - type:
52+
<code>Str</code> with possible values of <code>info</code>,
53+
<code>normal</code>, and <code>critical</code></li>
54+
<li><code>time</code> - a <a
55+
href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch time</a> of
56+
when the alert was issued - type: <code>UInt</code></li>
57+
<li><code>affects</code> - free-form, possibly-empty text describing
58+
what the alert affects (e.g. compiler version, parts of
59+
infrastructure, etc.) - type: <code>Str</code></li>
60+
<li><code>creator</code> - name of the creator of the alert, or
61+
string <code>Anonymous</code> if creator is not known to the site - type:
62+
<code>Str</code></li>
63+
</ul>
64+
65+
<h3 id="api-all">All Alerts</h3>
66+
67+
<p>To fetch all alerts, use
68+
<a href="::SITE-HOST::api/v1/all">::SITE-HOST::api/v1/all</a>. The alert
69+
objects will be available as an array in <code>alerts</code> property:</p>
70+
71+
<pre><code>::ESCAPE_HTML[::use WWW;
72+
my @alerts := jget('::SITE-HOST::api/v1/all')<alerts>;
73+
for @alerts {
74+
say join ' | ', "ID#{.<id>}", DateTime.new(.<time>),
75+
"severity: {.<severity>}";
76+
say join ' | ', ("affects: {.<affects>}" if .<affects>),
77+
"posted by: {.<creator>}";
78+
say .<alert>;
79+
say();
80+
}
81+
82+
# OUTPUT:
83+
# ID#5 | 2017-12-26T21:52:34Z | severity: info
84+
# affects: Rakudo 2017.12 and earlier | posted by: Zoffix Znet
85+
# wooots
86+
#
87+
# ID#4 | 2017-12-26T20:30:28Z | severity: info
88+
# affects: Rakudo 2017.12 and earlier | posted by: Zoffix Znet
89+
# Released some stuff
90+
#
91+
# ID#3 | 2017-12-26T20:30:18Z | severity: critical
92+
# affects: Rakudo 2017.12 and earlier | posted by: Zoffix Znet
93+
# OMG!!!! STUFF IS ON FIRE!!!::]ESCAPE_HTML::</code></pre>
94+
95+
<h3 id="api-alerts-since">Alerts Since…</h3>
96+
97+
<p>To fetch all alerts that were posted since a certain point of time, use
98+
<a href="::SITE-HOST::api/v1/since/1414325154">::SITE-HOST::api/v1/since/$UNIX_EPOCH_TIME</a>,
99+
where <code>$UNIX_EPOCH_TIME</code> is a <code>UInt</code>
100+
with <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch time</a>
101+
indicating non-inclusive time since which to fetch alerts from.
102+
The alert objects will be available in a possibly-empty array in
103+
<code>alerts</code> property:</p>
104+
105+
<pre><code>::ESCAPE_HTML[::use WWW;
106+
my $time = DateTime.now.earlier(:3days).Instant.to-posix.head.Int;
107+
if jget("::SITE-HOST::api/v1/since/$time").self<alerts> {
108+
for @^alerts {
109+
say join ' | ', "ID#{.<id>}", DateTime.new(.<time>),
110+
"severity: {.<severity>}";
111+
say join ' | ', ("affects: {.<affects>}" if .<affects>),
112+
"posted by: {.<creator>}";
113+
say .<alert>;
114+
say();
115+
}
116+
}
117+
else {
118+
say "No new alerts since {DateTime.new: $time}";
119+
}
120+
121+
# OUTPUT:
122+
# No new alerts since 2017-12-24T09:14:18.684577Z
123+
124+
125+
# ALERTNATIVE OUTPUT:
126+
# ID#5 | 2017-12-26T21:52:34Z | severity: info
127+
# affects: Rakudo 2017.12 and earlier | posted by: Zoffix Znet
128+
# wooots
129+
#
130+
# ID#4 | 2017-12-26T20:30:28Z | severity: info
131+
# affects: Rakudo 2017.12 and earlier | posted by: Zoffix Znet
132+
# Released some stuff
133+
::]ESCAPE_HTML::</code></pre>
134+
135+
<h3 id="api-alert">A Specific Alert</h3>
136+
137+
<p>To fetch a specific alert, use
138+
<a href="::SITE-HOST::api/v1/alert/2">::SITE-HOST::api/v1/alert/$ALERT_ID</a>,
139+
where <code>$ALERT_ID</code> is a <code>UInt</code> containing the unique ID
140+
of the alert you wish to retrieve.
141+
The end-point will return <code>404</code> error if alert is not found or
142+
a JSON object where the alert object is available in
143+
<code>alert</code> property:</p>
144+
145+
<pre><code>::ESCAPE_HTML[::use WWW;
146+
my $id = prompt 'Enter alert ID to fetch: ';
147+
with jget("::SITE-HOST::api/v1/alert/$id")<alert> {
148+
say join ' | ', "ID#{.<id>}", DateTime.new(.<time>),
149+
"severity: {.<severity>}";
150+
say join ' | ', ("affects: {.<affects>}" if .<affects>),
151+
"posted by: {.<creator>}";
152+
say .<alert>;
153+
}
154+
else {
155+
$^e.exception.message.say;
156+
}
157+
158+
# OUTPUT:
159+
# Enter alert ID to fetch: 42
160+
# Error 404: 404 Not Found
161+
162+
# ALERTNATIVE OUTPUT:
163+
# Enter alert ID to fetch: 5
164+
# ID#5 | 2017-12-26T21:52:34Z | severity: info
165+
# affects: Rakudo 2017.12 and earlier | posted by: Zoffix Znet
166+
# wooots::]ESCAPE_HTML::</code></pre>
167+
168+
</div>

0 commit comments

Comments
 (0)