Home
Articles
APIs
Kvarn
DNS
httPWM

This a document containing the usage of all the APIs I offer, for free. Always.

I will never store identifiable data, such as IP addresses, user-agent strings, etc.

The structure is as follows:

All error responses contain a reason header and a useful body. See the first example of the lookup API.

Contents
1 IP
1.1 GET
1.1.1 Description
1.1.2 Query
1.1.3 Response
2 DNS
2.2 Lookup
2.2.1 GET
2.2.1.1 Description
2.2.1.2 Query
2.2.1.3 Response
2.2.1.4 Examples
2.3 DNS over TLS check
2.3.2 GET
2.3.2.1 Description
2.3.2.2 Query
2.3.2.3 Response
2.3.2.4 Examples
3 Search
3.4 GET
3.4.3 Description
3.4.4 Query
3.4.5 Response
3.4.6 Examples
4 WebSocket ping pong
4.5 UPGRADE to `websocket`
4.5.1 Description
4.5.2 Response
5 AUTH
5.6 PUT & POST
5.6.1 Description
5.6.2 Response
5.7 DELETE
5.7.1 Description
5.7.2 Response

IP

/ip

GET

Description

Returns the IP address of the callee.

Query

No query parameters are considered.

Response

The IP address in plain text.

DNS

Lookup

/dns/lookup

GET

Description

Resolve the A, AAAA, MX, TXT, and CNAME records for a domain.

Uses my public resolver.

Query

Response

Each DNS record is on it’s own line (separated by \n, not \r\n) with the type followed by one space followed by the value.

Will always contain a trailing “\n”.

The value is the string of the destination domain in the case of MX & CNAME, the IP address in the case of A & AAAA and the content in case of a TXT.

If the domain can’t be resolved, a 404 will be returned.

Examples

$ curl -sI "https://icelk.dev/dns/lookup?domain=icelk.dev.dev" | grep "reason: "
reason: no DNS entry was found

I intentionally added a newline at the bottom to reflect the API. This isn’t how it’s displayed in a shell, but represents the string you’d get from a programming language HTTP request function.

$ curl "https://icelk.dev/dns/lookup?domain=icelk.dev"
A 78.69.142.191
MX mail.icelk.dev.

DNS over TLS check

/dns/check-dns-over-tls

GET

Description

Checks the DNS server at the IP address for DNS over TLS support for the domain.

Query

Response

Might return a 500 Internal Server Error if creating a DNS request failed.

If the server failed to respond before the timeout, used an invalid protocol, or failed the TLS check, the string unsupported is returned.

If everything checks out, supported is returned.

Examples

$ curl "https://icelk.dev/dns/check-dns-over-tls?ip=78.69.142.191&name=icelk.dev"
supported

Search

/search

GET

Description

Returns matches of q on the text of icelk.dev.

Query

The query format has the following rules (roughly).

icelk -(kvarn or agde) => “icelk and not (kvarn or agde)” (icelk or 10x-dev) (kvarn -agde) => (icelk or (10x and dev)) and (kvarn and not agde)

Response

A list of hits in JSON.

The scheme is described below.

[
    {
        rating: number, // the rating of the hit. All the output is sorted according to this.
        path: string, // the path to the document which contains the hit.
        start: number, // the byte at which the hit starts, mostly unimportant, as a different representation to the HTML is used when querying.
        associated_occurrences: number[], // starts of other occurrences which are required for this query. Mostly unimportant for the same reasons as `start`.
        context: string, // the surrounding text of the hit
        context_start_chars: number, // number of bytes in `context` before hit.
        context_start_bytes: number, // same as above, but with bytes instead. `context.get(context_start_bytes..)` is guaranteed to split on a valid UTF-8 codepoint. Though, don't trust a external web API!
    }
]

Examples

Here, everything is on the same line in the web response, but I’ve taken the freedom to remove all but the highest rated hit (by far) and use ... to signal all other.

$ curl "https://icelk.dev/search?q=next%20gen"
[
{"start":18,"rating":9.523809,"path":"/kvarn/index.html","context":"Kvarn\n\nKvarn is a next-generation web server designed for performanc","context_start_bytes":18,"context_start_chars":18,"associated_occurrences":[18,23]},
...
]

WebSocket ping pong

/ws-ping

UPGRADE to websocket

Description

A WebSocket endpoint which immediately responds with every incoming message.

This is a test for the Kvarn WebSocket support, and may be terminated at any time.

Response

A 101 Switching Protocols and a WebSocket conversation.

AUTH

/admin/auth

Powered by kvarn-auth. See it’s docs for more details.

PUT & POST

Description

An authentication route which gives you access to /admin.

I encourage you to try to crack the authentication.

Response

A response with an appropriate status code. If the login was successful, the cookies auth-jwt and auth-credentials are set using a set-cookie header.

DELETE

Description

Log out from the authentication.

Response

A 200 OK response which clears the auth cookies.