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
|
<!DOCTYPE html>
<html>
<style>
table{border-collapse:collapse;}
table,td,th{border:1px solid #000;padding:10px;}
span,table td{font-family:monospace;}
table td:nth-child(3),.uns{font-family:unset;}
table caption{font-weight:bold;margin:10px;}
</style>
<head>
<title>JAC's link shortener</title>
</head>
<body>
<h3>What is this?</h3>
<p>This is a link shortener. A sort of a backend practice, but it should run 24/7/53/<While I pay for my VPS> after I finish writing it.</p>
<h3>Documentation conventions</h3>
<p>All documentation assumes that the server is running <span>server.com</span> on port 80 without https, and you are trying to shorten a link to <span>example.com</span>.</p>
<p>All (non-global) parameters are mandatory, unless marked with question mark <span>?</span> sign.</p>
<p>PATH means part in url after the first slash: e.g. in link <span>http://server.com/short</span>, "short" is PATH, while URL means full shortened link.</p>
<h3>API reference</h3>
<p>The API follows this convention: everything is done through GET requests, client supplies all necessary parameters in URLencoded format.
Whatever server returns depends on parameters; it may be application/json (for programmable API) OR text/html (to render in HTML)</p>
<p>Example request: <span>http://ln.twistea.su/api/linkadd?url=https%3A%2F%2Fexample.com&format=html</span>.<br/>
This request may return something like: <span><a href="http://server.com/DEADF00D">your link: DEADF00D</a></span></p>
<p>Note: server may return json string like <span>null</span> or <span>true</span>: according to
<a href="https://www.rfc-editor.org/rfc/rfc8259#section-13">rfc-8259</a>, this is valid json and clients have to handle this accordingly.</p>
<p>Errors are returned like this: <span>{"error": description}</span> (some endpoints may return null / false to indicate failure).
Description may be any of the following: <ul>
<li><span>insufficient arguments</span>: not enough parameters provided to the endpoint.</li>
<li><span>invalid arguments</span>: argument's type/value does not match with what server expects.</li>
<li><span>occupied</span>: the path at which the link was attempted to be created is occupied already.</li>
<li><span>server error</span>: something went wrong on the server. Will include additional json field "what" with error message.</li>
<li><span>path too long</span>: the path is too long.</li>
<li><span>unknown</span>: server does not know what the hell went wrong</li>
</ul>Plese note that the HTTP return status for malformed request may be BAD_REQUEST (400), URI_TOO_LONG (414), NOT_FOUND (404) or INTERNAL_SERVER_ERROR (500)</p>
<table>
<thead>
<caption>Table 1. Global parameters (applicable to all endpoints)</caption>
<tr>
<th>Key</th>
<th>Value</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td>format</td>
<td><span>json | html</span></td>
<td>How to return the result of request. <tt>html</tt> should only be used to embed it in a web page.</td>
<td><span>json</span></td>
</tr>
<!--
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
-->
</tbody>
</table>
<table>
<thead>
<caption>Table 2. Endpoints description</caption>
<tr>
<th rowspan=2>Endpoint</th>
<th colspan=2>Parameters</th>
<th rowspan=2>Response object</th>
</tr>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan=2>/api/linkadd</td>
<td>url</td>
<td>string: a link to be shortened</td>
<td rowspan=2>{"url": "https://server.com/PATH"} | error
</td>
</tr>
<tr>
<td>try?</td>
<td class="uns">string: <span>PATH</span> to try to put link under <br/>
shoud match regex <span>[a-zA-Z0-9]+</span>, length ≤ 10 <br/>
may work with length = 11, but not always
<br/>
(if not occupied, WITHOUT <span>https://server.com/</span>)</td>
</tr>
<tr>
<td>/api/linkdel</td>
<td>path</td>
<td>string: PATH to delete the link from</td>
<td>true | false</td>
</tr>
<tr>
<td>/api/linkget</td>
<td>path</td>
<td>string: PATH to get link info from</td>
<td>{"url": "original url", created: int unix_timestamp}<br/>
OR null
</td>
</tr>
<tr>
<td>/PATH</td>
<td colspan=3 class="uns">Returns an HTML page with redirection message and returns <span>302 (HTTP_FOUND)</span>, with
<span>Location</span> header set to shortened URL</td>
</tr>
<td>/getargs</td>
<td colspan=3 class="uns">Get an HTML page with a list of all parameters provided to the endpoint. Used for testing.</td>
</tr>
</tbody>
</table>
<h3> Examples of API usage: </h3>
<p>This section is unfinished.</p>
</body>
</html>
|
