diff options
| author | justanothercatgirl <sotov@twistea.su> | 2025-03-27 12:52:11 +0300 |
|---|---|---|
| committer | justanothercatgirl <sotov@twistea.su> | 2025-03-27 12:52:11 +0300 |
| commit | 82742d5d13dc7b0691a79c79f8e62782fcb16e10 (patch) | |
| tree | 48d077549ed667d2a54171b82eb7608cb8edaf3e /www/docs.html | |
| parent | 8542ec17d3df989f3df9fd03af7a447bf730dc13 (diff) | |
Doing SQL (work in progress)
Diffstat (limited to 'www/docs.html')
| -rw-r--r-- | www/docs.html | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/www/docs.html b/www/docs.html new file mode 100644 index 0000000..a2fa287 --- /dev/null +++ b/www/docs.html @@ -0,0 +1,116 @@ +<!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>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) 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> + (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> |