103 lines
6.6 KiB
Smarty
103 lines
6.6 KiB
Smarty
{{- /*gotype: r00t2.io/clientinfo/server.Page*/ -}}
|
|
{{- define "usage" }}
|
|
{{- $page := . -}}
|
|
{{- $linkico := "🔗" }}
|
|
{{- template "meta.top" $page }}
|
|
<div class="jumbotron">
|
|
<h1>Usage</h1>
|
|
</div>
|
|
<h2 id="usage_params">Parameters<a href="#usage_params">{{ $linkico }}</a></h2>
|
|
<p>
|
|
You can control how the <a href="/">main page</a> displays/renders.
|
|
By default, it will try to "guess" what you want; e.g. if you access it in Chrome, it will return HTML but if you fetch via Curl, you'll get raw JSON
|
|
(or your specified data format; see below). If the classification of client can't be determined and an <code>Accept</code> wasn't specified,
|
|
a fallback to text-mode (by default <code>application/json</code>) will be returned.
|
|
<br/>
|
|
|
|
You can force a specific raw output by specifying the <a href="https://www.iana.org/assignments/media-types/media-types.xhtml">MIME type</a> via
|
|
<a href="https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.1">the <code>Accept</code> header (RFC 9110 § 12.5.1)</a>, which may be one of:
|
|
<ul>
|
|
<li><code>application/json</code> for JSON (<a href="https://www.rfc-editor.org/rfc/rfc8259.html">RFC 8259</a>, <a href="https://www.iana.org/assignments/media-types/application/json">IANA registration</a>)</li>
|
|
<li><code>application/xml</code> for XML (<a href="https://www.rfc-editor.org/rfc/rfc7303.html">RFC 7303</a>, <a href="https://www.iana.org/assignments/media-types/application/xml">IANA registration</a>)</li>
|
|
<li><code>application/yaml</code> for YAML (<a href="https://www.rfc-editor.org/rfc/rfc9512.html">RFC 9512</a>, <a href="https://www.iana.org/assignments/media-types/application/yaml">IANA registration</a>)</li>
|
|
<li><code>text/html</code> for HTML (<a href="https://www.rfc-editor.org/rfc/rfc2854.html">RFC 2854</a>, <a href="https://www.iana.org/assignments/media-types/text/html">IANA registration</a>)</li>
|
|
</ul>
|
|
For example: <code>Accept: application/json</code> will return JSON.
|
|
<br/>
|
|
|
|
If unspecified and it is a text-mode client (e.g. Curl), the default is <code>application/json</code>.
|
|
<code>text/html</code> may be used to force an HTML response from a text-only client,
|
|
just as one of the <code>application/*</code> MIME types above may be used to force that "raw" text MIME type for a "graphical" browser client.
|
|
The specification as defined by <a href="https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.1">RFC 9110 § 12.5.1</a> is completely
|
|
valid to pass and will be parsed without error (provided the header value is RFC-compliant and IANA-compliant),
|
|
though note that <code>application/xml</code> and <code>text/html</code>'s <code>charset</code> parameter will be entirely ignored;
|
|
the returned XML/HTML is <b>always</b> Unicode (with UTF-8 encoding).
|
|
<br/>
|
|
|
|
If no selectable MIME type is provided but an <code>Accept</code> was given, an error will be returned; specifically, a
|
|
<a href="https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.7"><code>406</code> status code (RFC 9110 § 15.5.7)</a>.
|
|
In this case, supported MIME types will be returned in the response's <code>Accept</code> header values, e.g.:
|
|
<p>
|
|
<pre>
|
|
Accept: application/json
|
|
Accept: application/xml
|
|
Accept: application/yaml
|
|
Accept: text/html
|
|
</pre>
|
|
</p>
|
|
|
|
Note that <a href="http://links.twibright.com/">Links</a>, <a href="https://lynx.invisible-island.net/">Lynx</a>, <a href="http://elinks.or.cz/">Elinks</a>,
|
|
and <a href="https://w3m.sourceforge.net/">W3M</a> are considered "graphical" browsers by this program as they are HTML-centric.
|
|
</p>
|
|
<p id="usage_params_mod">
|
|
The following parameters control/modify behavior.<a href="#usage_params_mod">{{ $linkico }}</a>
|
|
<ul>
|
|
<li>
|
|
<b><code>mime</code>:</b> Specify an explicit MIME type via URL instead of the <code>Accept</code> header as specified above.
|
|
<ul>
|
|
<li>This should only be used by clients in which it is impossible or particularly cumbersome to modify/specify headers.
|
|
<code>Accept</code> is more performant.</li>
|
|
<li>Only the first supported instance of this parameter will be used.</li>
|
|
<li>Any of the defined MIME types above may be specified (e.g. <code>?mime=application/json</code>).</li>
|
|
<li>If both this URL query parameter and the <code>Accept</code> header is specified, the URL query takes preference.</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<b><code>include</code>:</b> Include a <code><code></code> (or <code><pre></code>, depending on if indentation is needed/requested) block in the HTML for the specified MIME type as well.</li>
|
|
<ul>
|
|
<li>Only the first supported instance of this parameter will be used.</li>
|
|
<li>
|
|
The value <b>must</b> conform to the same rules/specifications as the <code>mime</code> parameter/<code>Accept</code> header.
|
|
<ul>
|
|
<li><code>include</code> may <b>not</b> be <code>text/html</code>; it will be ignored if this is set. Just learn to <code>ctrl+u</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Only used if the evaluated return is HTML, ignored otherwise.</li>
|
|
<li>Indentation can be specified via the <b>indent</b> parameter below (since indentation is otherwise meaningless to HTML returns).</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<b><code>indent</code>:</b> Enable/specify indentation for JSON and XML output; ignored for others.
|
|
<ul>
|
|
<li>The default is to not indent. (Commonly referred to as "condensed" or "compressed" JSON/XML.)</li>
|
|
<li>Only the first specified instance of this parameter will be used.</li>
|
|
<li>If specified with a string value, use that string as each indent.
|
|
<ul>
|
|
<li>Be mindful of URL query parameter encoding,
|
|
per <a href="https://www.rfc-editor.org/rfc/rfc3986.html#section-3.4">RFC 3986 § 3.4</a>
|
|
and <a href="https://www.rfc-editor.org/rfc/rfc8820.html#section-2.4">RFC 8820 § 2.4</a></li>
|
|
<li>For quick reference and as an example, to indent with a <a href="https://asciiref.dev/#c9">tab</a>
|
|
(<code>\t</code>, <code>0x09</code>) for each level, use <code>?indent=%09</code></li>
|
|
</ul>
|
|
</li>
|
|
<li>If indentation is specified without any value (<code>?indent</code>), the default is two
|
|
<a href="https://asciiref.dev/#c32">spaces</a> (<code>0x20</code>); this would be represented
|
|
as <code>?indent=%20%20</code></li>
|
|
<li><code>?indent=</code> (no value specified) is equal to <code>?indent</code>.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</p>
|
|
{{- template "meta.bottom" $page }}
|
|
{{- end }}
|