Za razvijalce — pseudobun.dev | OpenAPI, končne točke in datoteke za agente

Kaj to je in kaj ni

To je osebna spletna stran Urbana Vidoviča, ne produkt. Ni produktnega API-ja, sistema računov, API ključev, OAuth-a, webhookov ali peskovnika — če iščete kaj od tega, ste na napačni domeni. Kar obstaja, je tu dokumentirano pošteno in v celoti.

Vse spodnje je javno, brez avtentikacije in samo za branje. Ni se treba registrirati, prositi za dostop ali pošiljati žetona. Prosim, bodite razumni z obsegom zahtevkov: gostitelj samodejno blaži botovski promet, vztrajen avtomatiziran promet pa lahko to sproži in začasno postavi izziv vsem obiskovalcem strani.

Javne končne točke

GET /api/cv/: Izriše trenutni življenjepis v PDF in ga vrne kot priponko (`application/pdf`, ime datoteke `urban-vidovic-cv.pdf`). Ustvari se ob vsakem zahtevku iz istih izvornih podatkov kot HTML različica, zato se ne moreta razhajati. Ne sprejema parametrov.
GET /api/og/: Vrne predogledno sliko za družbena omrežja v velikosti 1200x630 (PNG), vključno z dnevnim posnetkom agregiranih javnih statistik prispevkov na GitHubu. Ne sprejema parametrov.

curl -sSL -o cv.pdf https://pseudobun.dev/api/cv/
curl -sSL -o preview.png https://pseudobun.dev/api/og/

Specifikacija OpenAPI

Celoten strojno berljiv opis je na /openapi.json. Gre za OpenAPI 3.1.0 z enoličnim `operationId` in opisom pri vsaki operaciji, tipiziranimi shemami odgovorov ter izrecno praznim varnostnim mehanizmom — po tem odjemalec loči, da poverilnice niso pričakovane, in ne le, da manjkajo.

curl -sS https://pseudobun.dev/openapi.json | jq '.paths | keys'

Napake

Vsaka napaka pod `/api` vrne `application/problem+json` in ne HTML strani z napako, zato odjemalcu nikoli ni treba luščiti sledi klicev. Telo vedno vsebuje stabilno kodo `code`, berljivo sporočilo `message`, namig `hint` z naslednjim korakom, `status` in `documentation_url`, ki kaže nazaj sem.

{
  "error": {
    "code": "not_found",
    "message": "No such endpoint.",
    "hint": "The published endpoints are GET /api/cv/ and GET /api/og/. See /openapi.json for the full specification.",
    "status": 404,
    "documentation_url": "https://pseudobun.dev/en/developers/"
  }
}

Opredeljene kode so `not_found` (404), `method_not_allowed` (405, z glavo `Allow`), `internal_error` (500) in `upstream_unavailable` (503).

Markdown za agente

Vsaka stran na tej strani ima predstavitev v obliki Markdown na istem URL-ju. Pošljite `Accept: text/markdown` in namesto HTML dobite Markdown, skladno z acceptmarkdown.com; ti odgovori nastavijo `Vary: Accept`. Zahtevek, ki ne sprejema ne `text/html` ne `text/markdown`, dobi `406`. Vrednosti kakovosti se upoštevajo, zato `text/markdown;q=0.9, text/html;q=0.8` vrne Markdown.

curl -sS -H "Accept: text/markdown" https://pseudobun.dev/sl/about/

Strojno berljive datoteke

/llms.txt: Kazalo strani v obliki llmstxt.org, vključno z izrecnim razdelkom o tem, kdaj stran uporabiti. Začnite tukaj.
/agent.txt: Ista navodila in opombe o protokolih, za orodja, ki preverjajo to pot.
/openapi.json: Opis zgornjih končnih točk v obliki OpenAPI 3.1.0.
/sitemap.xml: Vsi kanonični URL-ji s hreflang alternativami.
/robots.txt: Pravila za pajke.
/.well-known/keybase.txt: Podpisan dokaz, ki to domeno veže na identiteto na Keybase.

Odprtokodni projekti

Delo, opisano na tej strani, je večinoma javno. Izvorna koda spodnjih projektov je na GitHubu; vsak ima svojo dokumentacijo in postopek izdaje v lastnem repozitoriju, nič od tega pa ni postreženo s te domene.

Masca: MetaMask Snap za decentralizirano identiteto — upravljanje DID-ov in preverljivih poverilnic v denarnici MetaMask. masca.io
LutraID: Platforma za izdajo in preverjanje digitalnih dokumentov po standardih (OID4VCI, ISO mDoc). id.lutralabs.io
Swaylend: Posojilni protokol na omrežju Fuel, napisan v jeziku Sway. swaylend.com
EduCTX: Izobraževalne preverljive poverilnice, skladne s standardi W3C za decentralizirano identiteto. platform2.eductx.org

Stik

Vprašanja o integraciji, prijave napak v čemer koli zgoraj in prijave varnostnih ranljivosti pošljite na [email protected] — za občutljive vsebine uporabite PGP ključ na Keybase. Podrobnosti so na strani s kontaktom.