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:

• first heading level denotes the category.
• the next heading level is the name of the API (optional, e.g. IP doesn’t need this)
• the next is the HTTP method used can be multiple per API.
• the next level is metadata about the API.

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

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

• domain (required) - gives the domain of which to operate on

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 90.225.99.101
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

• ip (required) - the IP address for the DNS server
• name (required) - the domain to check the certificate against
• lookup-name (default: icelk.dev) - which domain to resolve. This should not matter.

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=90.225.99.101&name=icelk.dev"
supported

Search

/search

GET

Description

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

Query

• q (required) - the query to look up.

The query format has the following rules (roughly).

• Spaces and hyphens (-) are treated as AND.
• The literals AND, OR, NOT correspond accordingly. They are case-insensitive.
• - and ! are NOT.
• Parentheses can group items together.
• NOT must be next to an AND (“this and not that”)
• All text segments are case-insensitive.
• All test segments discard any non-alphanumerical characters.

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.